Flows

Container

Flow definitions are defined as a list of nodes, the first node being the entry into the flow. The simplest possible flow containing no nodes whatsoever (and therefore being a no-op) contains the following fields:

For example:

{
    "uuid": "b7bb5e7c-ad49-4e65-9e24-bf7f1e4ff00a",
    "name": "Empty Flow",
    "language": "eng",
    "type": "messaging",
    "nodes": []
}

Nodes

Flow definitions are composed of zero or more nodes, the first node is always the entry node.

A Node consists of:

At its simplest, a node can be just a single action with no exits, wait or router, such as:

{
    "uuid":"5a06445e-d790-4bd3-a10b-b47bdcc9abed",
    "actions":[{
        "uuid": "abc0a2bf-6b4a-4ee0-83e1-1eebae6948ac",
        "type": "send_msg",
        "text": "What is your name?"
    }]
}

If a node wishes to route to another node, it can do so by defining one or more exits, each with the UUID of the node that is next. Without a router defined, the first exit will always be taken.

An exit consists of:

{
    "uuid":"5a06445e-d790-4bd3-a10b-b47bdcc9abed",
    "actions":[{
        "uuid": "abc0a2bf-6b4a-4ee0-83e1-1eebae6948ac",
        "type": "send_msg",
        "text": "What is your name?"
    }],
    "exits": [{
        "uuid":"eb7defc9-3c66-4dfc-80bc-825567ccd9de",
        "destination_uuid":"ee0bee3f-34b3-4275-af78-f9ff52c82e6a"
    }]
}

Actions

Actions on a node generate events which can then be ingested by the engine container. In some cases the actions cause an immediate action, such as calling a webhook, in others the engine container is responsible for taking the action based on the event that is output, such as sending messages or updating contact fields. In either case the internal state of the engine is always updated to represent the new state so that flow execution is consistent. For example, while the engine itself does not have access to a contact store, it updates its internal representation of a contact’s state based on action performed on a flow so that later references in the flow are correct.

add_contact_groups

Can be used to add a contact to one or more groups. A contact_groups_changed event will be created for the groups which the contact has been added to.

Action 

{
    "type": "add_contact_groups",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "groups": [
        {
            "uuid": "1e1ce1e1-9288-4504-869e-022d1003c72a",
            "name": "Customers"
        }
    ]
}

Event 

{
    "type": "contact_groups_changed",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "groups_added": [
        {
            "uuid": "1e1ce1e1-9288-4504-869e-022d1003c72a",
            "name": "Customers"
        }
    ]
}

add_contact_urn

Can be used to add a URN to the current contact. A contact_urns_changed event will be created when this action is encountered.

Action 

{
    "type": "add_contact_urn",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "scheme": "tel",
    "path": "@results.phone_number.value"
}

Event 

{
    "type": "contact_urns_changed",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "urns": [
        "tel:+12024561111?channel=57f1078f-88aa-46f4-a59a-948a5739c03d",
        "twitterid:54784326227#nyaruka",
        "mailto:foo@bar.com",
        "tel:+12344563452"
    ]
}

add_input_labels

Can be used to add labels to the last user input on a flow. An input_labels_added event will be created with the labels added when this action is encountered. If there is no user input at that point then this action will be ignored.

Action 

{
    "type": "add_input_labels",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "labels": [
        {
            "uuid": "3f65d88a-95dc-4140-9451-943e94e06fea",
            "name": "Spam"
        }
    ]
}

Event 

{
    "type": "input_labels_added",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "input_uuid": "9bf91c2b-ce58-4cef-aacc-281e03f69ab5",
    "labels": [
        {
            "uuid": "3f65d88a-95dc-4140-9451-943e94e06fea",
            "name": "Spam"
        }
    ]
}

call_classifier

Can be used to classify the intent and entities from a given input using an NLU classifier. It always saves a result indicating whether the classification was successful, skipped or failed, and what the extracted intents and entities were.

Action 

{
    "type": "call_classifier",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "classifier": {
        "uuid": "1c06c884-39dd-4ce4-ad9f-9a01cbe6c000",
        "name": "Booking"
    },
    "input": "@input.text",
    "result_name": "Intent"
}

Event 

{
    "type": "service_called",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "service": "classifier",
    "classifier": {
        "uuid": "1c06c884-39dd-4ce4-ad9f-9a01cbe6c000",
        "name": "Booking"
    },
    "http_logs": [
        {
            "url": "http://test.acme.ai?classify",
            "status_code": 200,
            "request": "GET /?classify HTTP/1.1\r\nHost: test.acme.ai\r\nUser-Agent: Go-http-client/1.1\r\nAccept-Encoding: gzip\r\n\r\n",
            "response": "HTTP/1.0 200 OK\r\nContent-Length: 14\r\n\r\n{\"intents\":[]}",
            "elapsed_ms": 1000,
            "retries": 0,
            "status": "success",
            "created_on": "2019-10-16T13:59:30.123456789Z"
        }
    ]
}

call_llm

Can be used to call an LLM.

An llm_called event will be created if the LLM could be called.

Action 

{
    "type": "call_llm",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "llm": {
        "uuid": "14115c03-b4c5-49e2-b9ac-390c43e9d7ce",
        "name": "GPT-4"
    },
    "instructions": "Categorize the following text as positive or negative",
    "input": "@input.text",
    "output_local": "_llm_output"
}

Event 

{
    "type": "llm_called",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "llm": {
        "uuid": "14115c03-b4c5-49e2-b9ac-390c43e9d7ce",
        "name": "GPT-4"
    },
    "instructions": "Categorize the following text as positive or negative",
    "input": "Hi there",
    "output": "negative",
    "tokens_used": 123,
    "elapsed_ms": 0
}

call_resthook

Can be used to call a resthook.

A webhook_called event will be created for each subscriber of the resthook with the results of the HTTP call. If the action has result_name set, a result will be created with that name, and if the resthook returns valid JSON, that will be accessible through extra on the result.

Action 

{
    "type": "call_resthook",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "resthook": "new-registration"
}

Event 

[
    {
        "type": "resthook_called",
        "created_on": "2018-04-11T18:24:30.123456Z",
        "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
        "resthook": "new-registration",
        "payload": {
            "channel": {
                "address": "+17036975131",
                "name": "My Android Phone",
                "uuid": "57f1078f-88aa-46f4-a59a-948a5739c03d"
            },
            "contact": {
                "language": "eng",
                "name": "Ryan Lewis",
                "urn": "tel:+12024561111",
                "uuid": "5d76d86b-3bb9-4d5a-b822-c9d86f5d8e4f"
            },
            "flow": {
                "name": "Registration",
                "revision": 123,
                "uuid": "50c3706e-fedb-42c0-8eab-dda3335714b7"
            },
            "input": {
                "attachments": [
                    {
                        "content_type": "image/jpeg",
                        "url": "http://s3.amazon.com/bucket/test.jpg"
                    },
                    {
                        "content_type": "audio/mp3",
                        "url": "http://s3.amazon.com/bucket/test.mp3"
                    }
                ],
                "channel": {
                    "address": "+17036975131",
                    "name": "My Android Phone",
                    "uuid": "57f1078f-88aa-46f4-a59a-948a5739c03d"
                },
                "created_on": "2017-12-31T11:35:10.035757-02:00",
                "text": "Hi there",
                "type": "msg",
                "urn": {
                    "display": "(206) 555-1212",
                    "path": "+12065551212",
                    "scheme": "tel"
                },
                "uuid": "9bf91c2b-ce58-4cef-aacc-281e03f69ab5"
            },
            "path": [
                {
                    "arrived_on": "2018-04-11T18:24:30.123456Z",
                    "exit_uuid": "d7a36118-0a38-4b35-a7e4-ae89042f0d3c",
                    "node_uuid": "72a1f5df-49f9-45df-94c9-d86f7ea064e5",
                    "uuid": "c34b6c7d-fa06-4563-92a3-d648ab64bccb"
                },
                {
                    "arrived_on": "2018-04-11T18:24:30.123456Z",
                    "exit_uuid": "100f2d68-2481-4137-a0a3-177620ba3c5f",
                    "node_uuid": "3dcccbb4-d29c-41dd-a01f-16d814c9ab82",
                    "uuid": "5ecda5fc-951c-437b-a17e-f85e49829fb9"
                },
                {
                    "arrived_on": "2018-04-11T18:24:30.123456Z",
                    "exit_uuid": "d898f9a4-f0fc-4ac4-a639-c98c602bb511",
                    "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                    "uuid": "a4d15ed4-5b24-407f-b86e-4b881f09a186"
                },
                {
                    "arrived_on": "2018-04-11T18:24:30.123456Z",
                    "exit_uuid": "9fc5f8b4-2247-43db-b899-ab1ac50ba06c",
                    "node_uuid": "c0781400-737f-4940-9a6c-1ec1c3df0325",
                    "uuid": "b88ce93d-4360-4455-a691-235cbe720980"
                }
            ],
            "results": {
                "2factor": {
                    "category": "",
                    "category_localized": "",
                    "created_on": "2018-04-11T18:24:30.123456Z",
                    "input": "",
                    "name": "2Factor",
                    "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                    "value": "34634624463525"
                },
                "favorite_color": {
                    "category": "Red",
                    "category_localized": "Red",
                    "created_on": "2018-04-11T18:24:30.123456Z",
                    "input": "",
                    "name": "Favorite Color",
                    "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                    "value": "red"
                },
                "intent": {
                    "category": "Success",
                    "category_localized": "Success",
                    "created_on": "2018-04-11T18:24:30.123456Z",
                    "input": "Hi there",
                    "name": "Intent",
                    "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                    "value": "book_flight"
                },
                "phone_number": {
                    "category": "",
                    "category_localized": "",
                    "created_on": "2018-04-11T18:24:30.123456Z",
                    "input": "",
                    "name": "Phone Number",
                    "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                    "value": "+12344563452"
                },
                "webhook": {
                    "category": "Success",
                    "category_localized": "Success",
                    "created_on": "2018-04-11T18:24:30.123456Z",
                    "input": "GET http://127.0.0.1:49998/?content=%7B%22results%22%3A%5B%7B%22state%22%3A%22WA%22%7D%2C%7B%22state%22%3A%22IN%22%7D%5D%7D",
                    "name": "webhook",
                    "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                    "value": "200"
                }
            },
            "run": {
                "created_on": "2018-04-11T18:24:30.123456Z",
                "uuid": "8720f157-ca1c-432f-9c0b-2014ddc77094"
            }
        }
    },
    {
        "type": "webhook_called",
        "created_on": "2018-04-11T18:24:30.123456Z",
        "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
        "url": "http://127.0.0.1:49998/?cmd=success",
        "status_code": 200,
        "request": "POST /?cmd=success HTTP/1.1\r\nHost: 127.0.0.1:49998\r\nUser-Agent: goflow-testing\r\nContent-Length: 2838\r\nContent-Type: application/json\r\nAccept-Encoding: gzip\r\n\r\n{\"channel\":{\"address\":\"+17036975131\",\"name\":\"My Android Phone\",\"uuid\":\"57f1078f-88aa-46f4-a59a-948a5739c03d\"},\"contact\":{\"language\":\"eng\",\"name\":\"Ryan Lewis\",\"urn\":\"tel:+12024561111\",\"uuid\":\"5d76d86b-3bb9-4d5a-b822-c9d86f5d8e4f\"},\"flow\":{\"name\":\"Registration\",\"revision\":123,\"uuid\":\"50c3706e-fedb-42c0-8eab-dda3335714b7\"},\"input\":{\"attachments\":[{\"content_type\":\"image/jpeg\",\"url\":\"http://s3.amazon.com/bucket/test.jpg\"},{\"content_type\":\"audio/mp3\",\"url\":\"http://s3.amazon.com/bucket/test.mp3\"}],\"channel\":{\"address\":\"+17036975131\",\"name\":\"My Android Phone\",\"uuid\":\"57f1078f-88aa-46f4-a59a-948a5739c03d\"},\"created_on\":\"2017-12-31T11:35:10.035757-02:00\",\"text\":\"Hi there\",\"type\":\"msg\",\"urn\":{\"display\":\"(206) 555-1212\",\"path\":\"+12065551212\",\"scheme\":\"tel\"},\"uuid\":\"9bf91c2b-ce58-4cef-aacc-281e03f69ab5\"},\"path\":[{\"arrived_on\":\"2018-04-11T18:24:30.123456Z\",\"exit_uuid\":\"d7a36118-0a38-4b35-a7e4-ae89042f0d3c\",\"node_uuid\":\"72a1f5df-49f9-45df-94c9-d86f7ea064e5\",\"uuid\":\"c34b6c7d-fa06-4563-92a3-d648ab64bccb\"},{\"arrived_on\":\"2018-04-11T18:24:30.123456Z\",\"exit_uuid\":\"100f2d68-2481-4137-a0a3-177620ba3c5f\",\"node_uuid\":\"3dcccbb4-d29c-41dd-a01f-16d814c9ab82\",\"uuid\":\"5ecda5fc-951c-437b-a17e-f85e49829fb9\"},{\"arrived_on\":\"2018-04-11T18:24:30.123456Z\",\"exit_uuid\":\"d898f9a4-f0fc-4ac4-a639-c98c602bb511\",\"node_uuid\":\"f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03\",\"uuid\":\"a4d15ed4-5b24-407f-b86e-4b881f09a186\"},{\"arrived_on\":\"2018-04-11T18:24:30.123456Z\",\"exit_uuid\":\"9fc5f8b4-2247-43db-b899-ab1ac50ba06c\",\"node_uuid\":\"c0781400-737f-4940-9a6c-1ec1c3df0325\",\"uuid\":\"b88ce93d-4360-4455-a691-235cbe720980\"}],\"results\":{\"2factor\":{\"category\":\"\",\"category_localized\":\"\",\"created_on\":\"2018-04-11T18:24:30.123456Z\",\"input\":\"\",\"name\":\"2Factor\",\"node_uuid\":\"f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03\",\"value\":\"34634624463525\"},\"favorite_color\":{\"category\":\"Red\",\"category_localized\":\"Red\",\"created_on\":\"2018-04-11T18:24:30.123456Z\",\"input\":\"\",\"name\":\"Favorite Color\",\"node_uuid\":\"f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03\",\"value\":\"red\"},\"intent\":{\"category\":\"Success\",\"category_localized\":\"Success\",\"created_on\":\"2018-04-11T18:24:30.123456Z\",\"input\":\"Hi there\",\"name\":\"Intent\",\"node_uuid\":\"f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03\",\"value\":\"book_flight\"},\"phone_number\":{\"category\":\"\",\"category_localized\":\"\",\"created_on\":\"2018-04-11T18:24:30.123456Z\",\"input\":\"\",\"name\":\"Phone Number\",\"node_uuid\":\"f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03\",\"value\":\"+12344563452\"},\"webhook\":{\"category\":\"Success\",\"category_localized\":\"Success\",\"created_on\":\"2018-04-11T18:24:30.123456Z\",\"input\":\"GET http://127.0.0.1:49998/?content=%7B%22results%22%3A%5B%7B%22state%22%3A%22WA%22%7D%2C%7B%22state%22%3A%22IN%22%7D%5D%7D\",\"name\":\"webhook\",\"node_uuid\":\"f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03\",\"value\":\"200\"}},\"run\":{\"created_on\":\"2018-04-11T18:24:30.123456Z\",\"uuid\":\"8720f157-ca1c-432f-9c0b-2014ddc77094\"}}",
        "response": "HTTP/1.1 200 OK\r\nContent-Length: 16\r\nContent-Type: text/plain; charset=utf-8\r\nDate: Wed, 11 Apr 2018 18:24:30 GMT\r\n\r\n{ \"ok\": \"true\" }",
        "elapsed_ms": 0,
        "retries": 0,
        "status": "success",
        "resthook": "new-registration"
    }
]

call_webhook

Can be used to call an external service. The body, header and url fields may be templates and will be evaluated at runtime. A webhook_called event will be created based on the results of the HTTP call. If this action has a result_name, then additionally it will create a new result with that name. The value of the result will be the status code and the category will be Success or Failed. If the webhook returned valid JSON which is less than 10000 bytes, that will be accessible through extra on the result. The last JSON response from a webhook call in the current sprint will additionally be accessible in expressions as @webhook regardless of size.

Action 

{
    "type": "call_webhook",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "method": "GET",
    "url": "http://localhost:49998/?cmd=success",
    "headers": {
        "Authorization": "Token AAFFZZHH"
    },
    "result_name": "webhook"
}

Event 

{
    "type": "webhook_called",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "url": "http://localhost:49998/?cmd=success",
    "status_code": 200,
    "request": "GET /?cmd=success HTTP/1.1\r\nHost: localhost:49998\r\nUser-Agent: goflow-testing\r\nAuthorization: Token AAFFZZHH\r\nAccept-Encoding: gzip\r\n\r\n",
    "response": "HTTP/1.1 200 OK\r\nContent-Length: 16\r\nContent-Type: text/plain; charset=utf-8\r\nDate: Wed, 11 Apr 2018 18:24:30 GMT\r\n\r\n{ \"ok\": \"true\" }",
    "elapsed_ms": 0,
    "retries": 0,
    "status": "success"
}

enter_flow

Can be used to start a contact down another flow. The current flow will pause until the subflow exits or expires.

A flow_entered event will be created to record that the flow was started.

Action 

{
    "type": "enter_flow",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "flow": {
        "uuid": "b7cf0d83-f1c9-411c-96fd-c511a4cfa86d",
        "name": "Collect Language"
    }
}

Event 

{
    "type": "flow_entered",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "flow": {
        "uuid": "b7cf0d83-f1c9-411c-96fd-c511a4cfa86d",
        "name": "Collect Age"
    },
    "parent_run_uuid": "8720f157-ca1c-432f-9c0b-2014ddc77094",
    "terminal": false
}

open_ticket

Is used to open a ticket for the contact if they don’t already have an open ticket.

Action 

{
    "type": "open_ticket",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "topic": {
        "uuid": "472a7a73-96cb-4736-b567-056d987cc5b4",
        "name": "Weather"
    },
    "body": "@input",
    "assignee": {
        "email": "bob@nyaruka.com",
        "name": "Bob McTickets"
    },
    "result_name": "Help Ticket"
}

Event 

{
    "type": "run_result_changed",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "name": "Help Ticket",
    "value": "",
    "category": "Failure"
}

play_audio

Can be used to play an audio recording in a voice flow. It will generate an ivr_created event if there is a valid audio URL. This will contain a message which the caller should handle as an IVR play command using the audio attachment.

Action 

{
    "type": "play_audio",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "audio_url": "http://uploads.temba.io/2353262.m4a"
}

Event 

{
    "type": "ivr_created",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "688e64f9-2456-4b42-afcb-91a2073e5459",
    "msg": {
        "uuid": "b52a7f80-f820-4163-9654-8a7258fbaae4",
        "urn": "tel:+12065551212",
        "channel": {
            "uuid": "fd47a886-451b-46fb-bcb6-242a4046c0c0",
            "name": "Nexmo"
        },
        "text": "",
        "attachments": [
            "audio:http://uploads.temba.io/2353262.m4a"
        ],
        "locale": "eng-US"
    }
}

remove_contact_groups

Can be used to remove a contact from one or more groups. A contact_groups_changed event will be created for the groups which the contact is removed from. Groups can either be explicitly provided or all_groups can be set to true to remove the contact from all non-query based groups.

Action 

{
    "type": "remove_contact_groups",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "groups": [
        {
            "uuid": "b7cf0d83-f1c9-411c-96fd-c511a4cfa86d",
            "name": "Registered Users"
        }
    ]
}

Event 

{
    "type": "contact_groups_changed",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "groups_removed": [
        {
            "uuid": "b7cf0d83-f1c9-411c-96fd-c511a4cfa86d",
            "name": "Testers"
        }
    ]
}

request_optin

Can be used to send an optin to the contact if the channel supports that.

An optin_requested event will be created if the optin was requested.

Action 

{
    "type": "request_optin",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "optin": {
        "uuid": "248be71d-78e9-4d71-a6c4-9981d369e5cb",
        "name": "Joke Of The Day"
    }
}

Event 

[]

say_msg

Can be used to communicate with the contact in a voice flow by either reading a message with TTS or playing a pre-recorded audio file. It will generate an ivr_created event if there is a valid audio URL or backdown text. This will contain a message which the caller should handle as an IVR play command if it has an audio attachment, or otherwise an IVR say command using the message text.

Action 

{
    "type": "say_msg",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "text": "Hi @contact.name, are you ready to complete today's survey?",
    "audio_url": "http://uploads.temba.io/2353262.m4a"
}

Event 

{
    "type": "ivr_created",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "688e64f9-2456-4b42-afcb-91a2073e5459",
    "msg": {
        "uuid": "8ed05195-68cc-47fa-8e78-3bde7b3370ae",
        "urn": "tel:+12065551212",
        "channel": {
            "uuid": "fd47a886-451b-46fb-bcb6-242a4046c0c0",
            "name": "Nexmo"
        },
        "text": "Hi Ryan Lewis, are you ready to complete today's survey?",
        "attachments": [
            "audio:http://uploads.temba.io/2353262.m4a"
        ],
        "locale": "eng-US"
    }
}

send_broadcast

Can be used to send a message to one or more contacts. It accepts a list of URNs, a list of groups and a list of contacts.

The URNs and text fields may be templates. A broadcast_created event will be created for each unique urn, contact and group with the evaluated text.

Action 

{
    "type": "send_broadcast",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "urns": [
        "tel:+12065551212"
    ],
    "text": "Hi @contact.name, are you ready to complete today's survey?"
}

Event 

{
    "type": "broadcast_created",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "translations": {
        "eng": {
            "text": "Hi Ryan Lewis, are you ready to complete today's survey?"
        }
    },
    "base_language": "eng",
    "urns": [
        "tel:+12065551212"
    ]
}

send_email

Can be used to send an email to one or more recipients. The subject, body and addresses can all contain expressions.

An email_sent event will be created if the email could be sent.

Action 

{
    "type": "send_email",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "addresses": [
        "@urns.mailto"
    ],
    "subject": "Here is your activation token",
    "body": "Your activation token is @contact.fields.activation_token"
}

Event 

{
    "type": "email_sent",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "to": [
        "foo@bar.com"
    ],
    "subject": "Here is your activation token",
    "body": "Your activation token is AACC55"
}

send_msg

Can be used to reply to the current contact in a flow. The text field may contain templates. The action will attempt to find pairs of URNs and channels which can be used for sending. If it can’t find such a pair, it will create a message without a channel or URN.

A msg_created event will be created with the evaluated text.

Action 

{
    "type": "send_msg",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "text": "Hi @contact.name, are you ready to complete today's survey?",
    "template": {
        "uuid": "3ce100b7-a734-4b4e-891b-350b1279ade2",
        "name": "revive_issue"
    },
    "template_variables": [
        "@contact.name"
    ],
    "topic": "event"
}

Event 

{
    "type": "msg_created",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "msg": {
        "uuid": "27b67219-e599-4697-b62c-3c781ca3b5da",
        "urn": "tel:+12024561111?channel=57f1078f-88aa-46f4-a59a-948a5739c03d",
        "channel": {
            "uuid": "57f1078f-88aa-46f4-a59a-948a5739c03d",
            "name": "My Android Phone"
        },
        "text": "Hi Ryan Lewis, are you ready to complete today's survey?",
        "topic": "event",
        "locale": "eng-US"
    }
}

set_contact_channel

Can be used to change or clear the preferred channel of the current contact.

Because channel affinity is a property of a contact’s URNs, a contact_urns_changed event will be created if any changes are made to the contact’s URNs.

Action 

{
    "type": "set_contact_channel",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "channel": {
        "uuid": "4bb288a0-7fca-4da1-abe8-59a593aff648",
        "name": "Facebook Channel"
    }
}

Event 

[]

set_contact_field

Can be used to update a field value on the contact. The value is a localizable template and white space is trimmed from the final value. An empty string clears the value. A contact_field_changed event will be created with the corresponding value.

Action 

{
    "type": "set_contact_field",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "field": {
        "key": "gender",
        "name": "Gender"
    },
    "value": "Female"
}

Event 

{
    "type": "contact_field_changed",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "field": {
        "key": "gender",
        "name": "Gender"
    },
    "value": {
        "text": "Female"
    }
}

set_contact_language

Can be used to update the name of the contact. The language is a localizable template and white space is trimmed from the final value. An empty string clears the language. A contact_language_changed event will be created with the corresponding value.

Action 

{
    "type": "set_contact_language",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "language": "eng"
}

Event 

[]

set_contact_name

Can be used to update the name of the contact. The name is a localizable template and white space is trimmed from the final value. An empty string clears the name. A contact_name_changed event will be created with the corresponding value.

Action 

{
    "type": "set_contact_name",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "name": "Bob Smith"
}

Event 

{
    "type": "contact_name_changed",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "name": "Bob Smith"
}

set_contact_status

Can be used to update the status of the contact, e.g. to block or unblock the contact. A contact_status_changed event will be created with the corresponding value.

Action 

{
    "type": "set_contact_status",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "status": "blocked"
}

Event 

[
    {
        "type": "contact_status_changed",
        "created_on": "2018-04-11T18:24:30.123456Z",
        "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
        "status": "blocked"
    },
    {
        "type": "contact_groups_changed",
        "created_on": "2018-04-11T18:24:30.123456Z",
        "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
        "groups_removed": [
            {
                "uuid": "b7cf0d83-f1c9-411c-96fd-c511a4cfa86d",
                "name": "Testers"
            },
            {
                "uuid": "4f1f98fc-27a7-4a69-bbdb-24744ba739a9",
                "name": "Males"
            }
        ]
    }
]

set_contact_timezone

Can be used to update the timezone of the contact. The timezone is a localizable template and white space is trimmed from the final value. An empty string clears the timezone. A contact_timezone_changed event will be created with the corresponding value.

Action 

{
    "type": "set_contact_timezone",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "timezone": "Africa/Kigali"
}

Event 

{
    "type": "contact_timezone_changed",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "timezone": "Africa/Kigali"
}

set_run_local

Can be used to save a local variable. The local will be available in the context for the run as @locals.[local]. The value field can be a template and will be evaluated.

Action 

{
    "type": "set_run_local",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "local": "my_var",
    "value": "1",
    "operation": "increment"
}

Event 

[]

set_run_result

Can be used to save a result for a flow. The result will be available in the context for the run as @results.[name]. The optional category can be used as a way of categorizing results, this can be useful for reporting or analytics.

Both the value and category fields may be templates. A run_result_changed event will be created with the final values.

Action 

{
    "type": "set_run_result",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "name": "Gender",
    "value": "m",
    "category": "Male"
}

Event 

{
    "type": "run_result_changed",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "name": "Gender",
    "value": "m",
    "category": "Male"
}

start_session

Can be used to trigger sessions for other contacts and groups. A session_triggered event will be created and it’s the responsibility of the caller to act on that by initiating a new session with the flow engine.

Action 

{
    "type": "start_session",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "groups": [
        {
            "uuid": "1e1ce1e1-9288-4504-869e-022d1003c72a",
            "name": "Customers"
        }
    ],
    "flow": {
        "uuid": "b7cf0d83-f1c9-411c-96fd-c511a4cfa86d",
        "name": "Registration"
    },
    "exclusions": {
        "in_a_flow": true
    }
}

Event 

{
    "type": "session_triggered",
    "created_on": "2018-04-11T18:24:30.123456Z",
    "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
    "flow": {
        "uuid": "b7cf0d83-f1c9-411c-96fd-c511a4cfa86d",
        "name": "Collect Age"
    },
    "groups": [
        {
            "uuid": "1e1ce1e1-9288-4504-869e-022d1003c72a",
            "name": "Customers"
        }
    ],
    "exclusions": {
        "in_a_flow": true
    },
    "run_summary": {
        "uuid": "8720f157-ca1c-432f-9c0b-2014ddc77094",
        "flow": {
            "uuid": "50c3706e-fedb-42c0-8eab-dda3335714b7",
            "name": "Registration",
            "revision": 123
        },
        "contact": {
            "uuid": "5d76d86b-3bb9-4d5a-b822-c9d86f5d8e4f",
            "id": 1234567,
            "name": "Ryan Lewis",
            "language": "eng",
            "status": "active",
            "timezone": "America/Guayaquil",
            "created_on": "2018-06-20T11:40:30.123456789Z",
            "last_seen_on": "2017-12-31T11:35:10.035757258-02:00",
            "urns": [
                "tel:+12024561111?channel=57f1078f-88aa-46f4-a59a-948a5739c03d",
                "twitterid:54784326227#nyaruka",
                "mailto:foo@bar.com"
            ],
            "groups": [
                {
                    "uuid": "b7cf0d83-f1c9-411c-96fd-c511a4cfa86d",
                    "name": "Testers"
                },
                {
                    "uuid": "4f1f98fc-27a7-4a69-bbdb-24744ba739a9",
                    "name": "Males"
                }
            ],
            "fields": {
                "activation_token": {
                    "text": "AACC55"
                },
                "age": {
                    "text": "23",
                    "number": 23
                },
                "gender": {
                    "text": "Male"
                },
                "join_date": {
                    "text": "2017-12-02",
                    "datetime": "2017-12-02T00:00:00.000000-02:00"
                }
            },
            "ticket": {
                "uuid": "78d1fe0d-7e39-461e-81c3-a6a25f15ed69",
                "topic": {
                    "uuid": "472a7a73-96cb-4736-b567-056d987cc5b4",
                    "name": "Weather"
                },
                "assignee": {
                    "email": "bob@nyaruka.com",
                    "name": "Bob"
                }
            }
        },
        "status": "completed",
        "results": {
            "2factor": {
                "name": "2Factor",
                "value": "34634624463525",
                "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                "created_on": "2018-04-11T18:24:30.123456Z"
            },
            "favorite_color": {
                "name": "Favorite Color",
                "value": "red",
                "category": "Red",
                "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                "created_on": "2018-04-11T18:24:30.123456Z"
            },
            "intent": {
                "name": "Intent",
                "value": "book_flight",
                "category": "Success",
                "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                "input": "Hi there",
                "extra": {
                    "intents": [
                        {
                            "name": "book_flight",
                            "confidence": 0.5
                        },
                        {
                            "name": "book_hotel",
                            "confidence": 0.25
                        }
                    ],
                    "entities": {
                        "location": [
                            {
                                "value": "Quito",
                                "confidence": 1
                            }
                        ]
                    }
                },
                "created_on": "2018-04-11T18:24:30.123456Z"
            },
            "phone_number": {
                "name": "Phone Number",
                "value": "+12344563452",
                "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                "created_on": "2018-04-11T18:24:30.123456Z"
            },
            "webhook": {
                "name": "webhook",
                "value": "200",
                "category": "Success",
                "node_uuid": "f5bb9b7a-7b5e-45c3-8f0e-61b4e95edf03",
                "input": "GET http://127.0.0.1:49998/?content=%7B%22results%22%3A%5B%7B%22state%22%3A%22WA%22%7D%2C%7B%22state%22%3A%22IN%22%7D%5D%7D",
                "extra": {
                    "results": [
                        {
                            "state": "WA"
                        },
                        {
                            "state": "IN"
                        }
                    ]
                },
                "created_on": "2018-04-11T18:24:30.123456Z"
            }
        }
    },
    "history": {
        "parent_uuid": "d2f852ec-7b4e-457f-ae7f-f8b243c49ff5",
        "ancestors": 1,
        "ancestors_since_input": 0
    }
}

transfer_airtime

Attempts to make an airtime transfer to the contact.

An airtime_transferred event will be created if the airtime could be sent.

Action 

{
    "type": "transfer_airtime",
    "uuid": "8eebd020-1af5-431c-b943-aa670fc74da9",
    "amounts": {
        "RWF": 500,
        "USD": 0.5
    },
    "result_name": "Reward Transfer"
}

Event 

[
    {
        "type": "airtime_transferred",
        "created_on": "2018-04-11T18:24:30.123456Z",
        "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
        "transfer_uuid": "b504fe9e-d8a8-47fd-af9c-ff2f1faac4db",
        "external_id": "G5NTXHPHWN",
        "sender": "tel:+17036975131",
        "recipient": "tel:+12024561111?channel=57f1078f-88aa-46f4-a59a-948a5739c03d",
        "currency": "RWF",
        "amount": 500,
        "http_logs": [
            {
                "url": "http://send.airtime.com",
                "status_code": 200,
                "request": "GET / HTTP/1.1\r\nHost: send.airtime.com\r\nUser-Agent: Go-http-client/1.1\r\nAccept-Encoding: gzip\r\n\r\n",
                "response": "HTTP/1.0 200 OK\r\nContent-Length: 15\r\n\r\n{\"status\":\"ok\"}",
                "elapsed_ms": 0,
                "retries": 0,
                "status": "success",
                "created_on": "2019-10-16T13:59:30.123456789Z"
            }
        ]
    },
    {
        "type": "run_result_changed",
        "created_on": "2018-04-11T18:24:30.123456Z",
        "step_uuid": "b88ce93d-4360-4455-a691-235cbe720980",
        "name": "Reward Transfer",
        "value": "G5NTXHPHWN",
        "category": "Success"
    }
]