Flow

Overview

The Flow in VoIPBIN is a powerful set of instructions that guides the platform on how to handle incoming calls. When someone calls one of your VoIPBIN numbers or destinations, the platform looks up the associated URL and sends a request. The Flow instructions are then read to determine the appropriate actions to be taken, such as recording the call, playing a message, or prompting the caller to press digits on their keypad.

At its core, the Flow is an array of JSON objects with special tags defined by VoIPBIN, enabling users to build their own Programmable Voice applications.

How the flow works

When an incoming call is received on one of your VoIPBIN numbers or destinations, the platform identifies the associated URL and sends a request.

The Flow instructions are then processed, providing a step-by-step guide on how to handle the call. This might involve greeting the caller, presenting options, gathering input, or executing various actions based on the caller’s response.

Unified flow

VoIPBIN’s Unified Flow feature is a game-changer, allowing users to create a single flow that can be attached to multiple communication channels, including voice and video calls, SMS, and RESTful API triggers.

With Unified Flow, users can design a custom flow that defines the actions to be taken when a specific channel request is received. VoIPBIN then automatically executes this flow, ensuring a consistent experience for customers across various channels.

Non-linear action execution

VoIPBIN’s Flow provides the flexibility of Non-Linear action execution.

Users can customize their actions in both linear and non-linear ways, allowing them to define complex logic and decision trees to handle various call scenarios.

Flow fork

Certain flow actions, such as fetch, fetch_flow, queue_join, and more, enable flow forking.

When the flow is forked, the execution cursor moves to the forked flow and starts executing the actions within it. Once the forked flow reaches its end, the execution cursor moves back to the following action of the forking action, continuing the flow execution.

Actions

Within VoIPBIN, actions dictate the course of the platform’s response in a given flow, encompassing tasks such as initiating calls, playing sounds or prompts, activating text-to-speech, sending SMS or DTMFs, and dispatching SNS messages. These diverse actions serve as indispensable building blocks for crafting customized voice applications, ensuring the creation of uniquely tailored call experiences for users.

VoIPBIN’s Flow provides developers with a versatile and robust toolkit, empowering them to forge dynamic voice applications, efficiently manage incoming calls, and curate personalized call encounters. Through its non-linear execution, cohesive flow capabilities, and an array of actions including SMS, DTMFs, SNS messages, and more, VoIPBIN’s Flow unveils limitless possibilities for the development of sophisticated and interactive voice applications, precisely tailored to meet specific business needs.

Flow execution

In VoIPBin, the execution of flows is versatile and can be initiated through various methods:

Incoming/Outgoing Calls:

VoIPBin facilitates flow execution with both incoming and outgoing calls. Users have the option to register a flow to a specific number. Upon an incoming call to the registered number, VoIPBin will seamlessly execute the associated flow. Users can also initiate a call with a predefined flow. Once the outgoing call is answered, the attached flow will be triggered.

Received Messages:

VoIPBin allows users to register flows to received messages. When a message is received, the registered flow will be executed. For example, you can register the flow like the below.

...
{
  "type": "branch",
  "option": {
    "variable": "voipbin.message.text",
    "target_ids": {
      "call me": "7a1e8c4c-aaea-11ed-9f0f-bffcc31ca3c3",
      "text me": "79fd8c9a-aaea-11ed-a238-0b094a49c637",
      "text developer": "73107b70-d56b-4b47-b331-dc4f2ac43a5b"
    }
  }
}
...

In the provided example, the system examines the content of the received message using voipbin.message.text and proceeds to compare the message text. Should the message text match the specified criterion, such as “call me,” the flow execution cursor will be directed to the designated action ID (7a1e8c4c-aaea-11ed-9f0f-bffcc31ca3c3) for subsequent execution. See detail about available variables at here.

Outbound Campaigns:

The VoIPBin platform integrates flows into outbound campaigns, providing a structured and automated approach to execution.

API:

Users have the flexibility to trigger flows through API calls. This API integration empowers developers to seamlessly incorporate and activate flows within their applications. These diverse methods offer users and developers flexibility in integrating and executing flows based on their specific needs and scenarios. See detail about API calling at here. And due to the absence of any media-based incoming or outgoing elements in the API, certain actions within the flow—such as answer, talk, transcribe, and others—will be ignored. Instead, the execution cursor will proceed to the next action in the sequence.

Flow

{
    "id": "<string>",
    "type": "flow",
    "name": "test conference_join",
    "detail": "test flow for conference_join",
    "actions": [
        ...
    ],
    "tm_create": "2022-02-03 05:37:48.545532",
    "tm_update": "2022-02-03 06:10:23.604222",
    "tm_delete": "9999-01-01 00:00:00.000000"
},

id: Flow’s ID.
type: Flow’s types. See detail here.
name: Flow’s name.
detail: Flow’s detail.
actions: List of actions. See detail here.

Example .. code:

{
    "id": "ff8e4528-a743-4913-948c-81abaf563f80",
    "type": "flow",
    "name": "test flow for message sending",
    "detail": "test scenario for sending a test message.",
    "actions": [
        {
            "id": "605f5650-ba92-4dcd-bdac-91fcf6260939",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "message_send",
            "option": {
                "text": "hello, this is test message.",
                "source": {
                    "type": "tel",
                    "target": "+821021656521"
                },
                "destinations": [
                    {
                        "type": "tel",
                        "target": "+31616818985"
                    }
                ]
            }
        }
    ],
    "tm_create": "2022-03-21 02:11:15.033396",
    "tm_update": "9999-01-01 00:00:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Type

type	Description
flow	Normal flow.

Action

{
    "id": "<string>>",
    "next_id": "<string>>",
    "type": "<string>>",
    "option": {
        ...
    },
    "tm_execute": "<string>>"
}

id: Action’s id.
next_id: Action’s next id. If it sets empty, just move on to the next action in the action array.
type: Action’s type. See detail here.
option: Action’s option.

Type

type	Description
agent_call	Deprecated. Use the connect instead. Creates a call to the agent and connect.
amd	Answering machine detection.
answer	Answer the call.
beep	Play the beep sound.
branch	Branch gets the variable then execute the correspond action. For example. gets the dtmf input saved variable and jump to the action.
call	Starts a new independent outgoing call with a given flow.
chatbot_talk	Starts a talk with chatbot.
condition_call_digits	Deprecated. Use the condition_variable instead. Condition check(call’s digits).
condition_call_status	Deprecated. Use the condition_variable instead. Condition check(call’s status).
condition_datetime	Condition check(time)
condition_variable	Condition check(variable).
confbridge_join	Join to the confbridge.
conference_join	Join to the conference.
connect	Creates a new call to the destinations and connects to them.
conversation_send	Send a message to the conversation.
digits_receive	Receive the digits(dtmfs).
digits_send	Send the digits(dtmfs).
echo	Echo to stream.
external_media_start	Start the external media.
external_media_stop	Stop the external media.
fetch	Fetch the actions from endpoint.
fetch_flow	Fetch the actions from the exist flow.
goto	Goto.
hangup	Hangup the call.
hangup_relay	Hangs up the call with the same reason of the given reference id.
message_send	Send a message.
play	Play the file of the given urls.
queue_join	Join to the queue.
recording_start	Start the record of the given call.
recording_stop	Stop the record of the given call.
sleep	Sleep.
stop	Stop the flow.
stream_echo	Echo the steam.
talk	Generate audio from the given text(ssml or plain text) and play it.
transcribe_start	Start transcribe the call
transcribe_stop	Stop transcribe the call
transcribe_recording	Transcribe the recording and send it to webhook.
variable_set	Sets the variable.
webhook_send	Send a webhook.

Agent Call

Calling the agent. The agent may have various types of addresses or phone numbers, such as a desk phone, mobile phone, or softphone application.

Parameters

{
    "type": "agent_call",
    "option": {
        "agent_id": "<string>"
    }
}

agent_id: target agent id.

Example

{
    "type": "agent_call",
    "option": {
        "agent_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b"
    }
}

AMD

Answering machine detection.

Parameters

{
    "type": "amd",
    "option": {
        "machine_handle": "<string>",
        "async": <boolean>
    }
}

machine_handle: hangup,delay,continue if the machine answered a call. See detail here.
async: if it’s false, the call flow will be stop until amd done.

Machine handle

Type	Description
hangup	Hangup the call.
continue	Continue the call.

Example

{
    "type": "amd",
    "option": {
        "machine_handle": "hangup",
        "sync": true
    }
}

Answer

Answer the call

Parameters

{
    "type": "answer"
}

Example

{
    "type": "answer"
}

Beep

Make a beep sound.

Parameters

{
    "type": "beep"
}

Example

{
    "type": "beep"
}

Branch

Branch the flow. It gets the variable from the activeflow and move the activeflow cursor to the selected target id.

Parameters

{
    "type": "branch",
    "option": {
        "variable": "<string>",
        "default_target_id": "<string>",
        "target_ids": {
            "<string>": <string>,
        }
    }
}

variable: Target variable. If this value is empty, default target variable will be selected. Available variables are listed here. default: voipbin.call.digits
default_target_id: action id for default selection. This will be generated automatically by the given default_index.
target_ids: set of input digit and target id fair. This will be generated automatically by the given target_indexes.

Example

{
    "type": "branch",
    "option": {
        "default_target_id": "ed9705ca-c524-11ec-a3fb-8feb7731ad45",
        "target_ids": {
            "1": "c3eb8e62-c524-11ec-94c5-abafec8af561",
            "2": "dc87123e-c524-11ec-89c6-5fb18da14034",
            "3": "e70fb030-c524-11ec-b657-ebec72f097ef"
        }
    }
}

Call

Make a new outbound call in a new context.

Parameters

{
    "type": "call",
    "option": {
        "source": {
            ...
        },
        "destinations": [
            {
                ...
            },
            ...
        ],
        "flow_id": "<string>"
        "actions": [
            {
                ...
            }
        ],
        "chained": <boolean>,
        "early_execution": <boolean>
    }
}

source: Source address. See detail here.
destinations: Array of destination addresses. See detail here.
flow_id: Call’s flow id. If this not set, will use the actions array.
actions: Array of actions. If the flow_id not set, the call flow will be created with this actions.
chained: If it sets to true, created calls will be hungup when the master call is hangup. Default false.
early_execution: It it sets to true, the voipbin will execute the flow when then call is ringing.

Example

{
    "id": "e34ab97a-c53a-4eb4-aebf-36767a528f00",
    "next_id": "00000000-0000-0000-0000-000000000000",
    "type": "call",
    "option": {
        "source": {
            "type": "tel",
            "target": "+821100000001"
        },
        "destinations": [
            {
                "type": "tel",
                "target": "+821100000002"
            }
        ],
        "actions": [
            {
                "type": "talk",
                "option": {
                    "text": "hello, this is test message.",
                    "gender": "female",
                    "language": "en-US"
                }
            }
        ],
        "chained": false
    }
}

Chatbot Talk

Start the chatbot talk.

Parameters

{
    "type": "chatbot_talk",
    "option": {
        "chatbot_id": "<string>",
        "gender": "<string>",
        "language": "<string>",
        "duration": <number>
    }
}

chatbot_id: Chatbot id.
gender: Voice gender. male/female/neutral
language: Specifies the language. BCP47 format.
duration: Duration. Seconds.

Confbridge Join

Join to the confbridge.

Parameters

{
    "type": "confbridge_join",
    "option": {
        "confbridge_id": "<string>"
    }
}

confbridge_id: Target confbridge id.

Condition Call Digits

Deprecated. Use the condition_variable instead. Check the condition of received digits. If the conditions are met, the system proceeds to the next action. If the conditions are not met, the voipbin directs the call to a false_target_id for further processing.

Parameters

{
    "type": "condition_call_digits",
    "option": {
        "length": <number>,
        "key": "<string>",
        "false_target_id": "<string>"
    }
}

length: match digits length.
key: match digits contain.
false_target_id: action id for false condition.

Example

{
    "type": "condition_call_digits",
    "option": {
        "length": 10,
        "false_target_id": "e3e50e6c-9c8b-11ec-8031-0384a8fcd1e2"
    }
}

Condition Call Status

Deprecated. Use the condition_variable instead. Check the condition of call’s status. It checks the call’s status and if it matched with condition then move to the next action. If not, move to the false_target_id.

Parameters

{
    "type": "condition_call_status",
    "option": {
        "status": <number>,
        "false_target_id": "<string>"
    }
}

status: match call’s status. See detail here.
false_target_id: action id for false condition.

Example

{
    "type": "condition_call_status",
    "option": {
        "status": "progressing,
        "false_target_id": "e3e50e6c-9c8b-11ec-8031-0384a8fcd1e2"
    }
}

Condition Datetime

Check the condition of the time. It checks the current time(UTC) and if it matched with condition then move to the next action. If not, move to the false_target_id.

Parameters

{
    "type": "condition_datetime",
    "option": {
        "condition": <number>,

        "minute": <number>,
        "hour": <number>,
        "day": <number>,
        "month": <number>,
        "weekdays": [
            <number>,
            ...
        ],


        "false_target_id": "<string>"
    }
}

condition: Match condition. One of “==”, “!=”, “>”, “>=”, “<”, “<=”.
minute: Minutes. -1 for all minutes.
hour: Hour. -1 for all hours.
day: Day. -1 for all days.
month: Month. 0 for all months.
weekdays: List of weekdays. Sunday: 0, Monday: 1, Tuesday: 2, Wednesday: 3, Thursday: 4, Friday: 5, Saturday: 6
false_target_id: action id for false condition.

Example

{
    "type": "condition_datetime",
    "option": {
        "condition": ">=,
        "minute": 0
        "hour": 8,
        "day": -1,
        "month": 0,
        "weekdays": [],
        "false_target_id": "d08582ee-1b3d-11ed-a43e-9379f27c3f7f"
    }
}

Condition Variable

Check the condition of the given variable. It checks the call’s status and if it matched with condition then move to the next action. If not, move to the false_target_id.

Parameters

{
    "type": "condition_variable",
    "option": {
        "condition": "<string>",
        "variable": "<string>",
        "value_type": "<string>",
        "value_string": "<string>",
        "value_number": <number>,
        "value_length": <number>,
        "false_target_id": "<string>"
    }
}

condition: Match condition. One of “==”, “!=”, “>”, “>=”, “<”, “<=”.
variable: Target variable. See detail here.
value_type: Type of value. string/number/length.
value_string: Value. Valid only if the value_type is string.
value_number: * value_string: Value. Valid only if the value_type is number.
value_length: * value_string: Value. Valid only if the value_type is length.
false_target_id: action id for false condition.

Example

{
    "type": "condition_variable",
    "option": {
        "condition": "==",
        "variable": "voipbin.call.source.target",
        "value_type": "string",
        "value_string": "+821100000001",
        "false_target_id": "fb2f4e2a-b030-11ed-bddb-976af892f5a3"
    }
}

Conference Join

Join to the conference

Parameters

{
    "type": "conference_join",
    "option": {
        "conference_id": "<string>"
    }
}

conference_id: Conference’s id to join.

Example

{
    "type": "conference_join",
    "option": {
        "conference_id": "367e0e7a-3a8c-11eb-bb08-f3c3f059cfbe"
    }
}

Connect

Originate to the other destination(s) and connect to them each other.

Parameters

{
    "type": "connect",
    "option": {
        "source": {...},
        "destinations": [
            ...
        ],
        "early_media": <boolean>,
        "relay_reason": <boolean>
    }
}

source: Source address. See detail here.
destinations: Array of destination addresses. See detail here.
early_media: Support early media.
relay_reason: relay the hangup reason to the master call.

Example

{
    "type": "connect",
    "option": {
        "source": {
            "type": "tel",
            "target": "+11111111111111"
        },
        "destinations": [
            {
                "type": "tel",
                "target": "+222222222222222"
            }
        ]
    }
}

Conversation send

Send the message to the conversation.

Parameters

{
    "type": "conversation_send",
    "option": {
        "conversation_id": "<string>",
        "text": "<string>",
        "sync": <boolean>
    }
}

conversation_id: Target conversation id.
text: Send text message.
sync: If this set to true, waits until this action done.

Example

{
    "type": "conversation_send",
    "option": {
        "conversation_id": "b5ef5e64-f7ca-11ec-bbe9-9f74186a2a72",
        "text": "hello world, this is test message.",
        "sync": false
    }
}

Digits Receive

Receives the digits for given duration or numbers.

Parameters

{
    "type": "digits_receive",
    "option": {
        "duration": <number>,
        "length": <number>,
        "key": "<string>"
    }
}

duration: The duration allows you to set the limit (in ms) that VoIPBIN will wait for the endpoint to press another digit or say another word before it continue to the next action.
length: You can set the number of DTMFs you expect. An optional limit to the number of DTMF events that should be gathered before continuing to the next action. By default, this is set to 1, so any key will trigger the next step. If EndKey is set and MaxNumKeys is unset, no limit for the number of keys that will be gathered will be imposed. It is possible for less keys to be gathered if the EndKey is pressed or the timeout being reached.
key: If set, determines which DTMF triggers the next step. The finish_on_key will be included in the resulting variable. If not set, no key will trigger the next action.

Example

{
    "type": "digits_receive",
    "option": {
        "duration": 10000,
        "length": 3,
        "key": "#"
    }
}

Digits Send

Sends the digits with given duration and interval.

Parameters

{
    "type": "digits_send",
    "option": {
        "digits": "<string>",
        "duration": <number>,
        "interval": <number>
    }
}

digits: The digit string to send. Allowed set of characters: 0-9,A-D, #, ‘*’; with a maximum of 100 keys.
duration: The duration of DTMF tone per key in milliseconds. Allowed values: Between 100 and 1000.
interval: Interval between sending keys in milliseconds. Allowed values: Between 0 and 5000.

Example

{
    "type": "digits_send",
    "option": {
        "digits": "1234567890",
        "duration": 500,
        "interval": 500
    }
},

Echo

Echoing the call.

Parameters

{
    "type": "echo",
    "option": {
        "duration": <number>,
    }
}

duration: Echo duration. ms.

Example

{
    "type": "echo",
    "option": {
        "duration": 30000
    }
}

External Media Start

Start the external media.

Parameters

{
    "type": "external_media_start",
    "option": {
        "external_host": "<string>",
        "encapsulation": "<string>",
        "transport": "<string>",
        "connection_type": "<string>",
        "format": "<string>",
        "direction": "<string>",
        "data": "<string>"
    }
}

external_host: external media target host address.
encapsulation: encapsulation. default: rtp.
transport: transport. default: udp.
connection_type: connection type. default: client
format: format default: ulaw
direction: Direction. default: both.
data: Data. Reserved.

External Media Stop

Stop the external media.

Parameters

{
    "type": "external_media_stop",
}

Fetch

Fetch the next flow from the remote.

Parameters

{
    "type": "fetch",
    "option": {
        "event_url": "<string>",
        "event_method": "<string>"
    }
}

event_url: The url for flow fetching.
event_method: The method for flow fetching.

Example

{
    "type": "fetch".
    "option": {
        "event_method": "POST",
        "event_url": "https://webhook.site/e47c9b40-662c-4d20-a288-6777360fa211"
    }
}

Fetch Flow

Fetch the next flow from the existed flow.

Parameters

{
    "type": "fetch_flow",
    "option": {
        "flow_id": "<string>"
    }
}

flow_id: The id of flow.

Example

{
    "type": "fetch_flow".
    "option": {
        "flow_id": "212a32a8-9529-11ec-8bf0-8b89df407b6e"
    }
}

Goto

Move the action execution.

Parameters

{
    "type": "goto",
    "option": {
        "target_id": "<string>",
        "loop_count": <integer>
    }
}

target_id: action id for move target.
loop_count: The number of loop.

Example

{
    "type": "goto",
    "option": {
        "target_id": "ca4ddd74-9c8d-11ec-818d-d7cf1487e8df",
        "loop_count": 2
    }
}

Hangup

Hangup the call.

Parameters

{
    "type": "hangup"
}

Example

{
    "type": "hangup"
}

Hangup Relay

Hangup the call and relay the hangup cause to the reference id.

Parameters

{
    "type": "Hangup_relay"
    "option": {
        "reference_id": "<string>"
    }
}

Example

{
    "type": "hangup_relay",
    "option": {
        "reference_id": "b8573f30-b031-11ed-ac05-3bc9a62e64c3"
    }
}

Message send

Send a message.

Parameters

{
    "type": "message_send",
    "option": {
        "source": {
            ...
        },
        "destinations": [
            {
                ...
            },
            ...
        ],
        "text": "<string>"
    }
}

source: Source address info. See detail here.
destinations: Array of destination addresses. See detail here.
text: Message’s text.

Play

Plays the linked file.

Parameters

{
    "type": "play",
    "option": {
        "stream_urls": [
            "<string>",
            ...
        ]
    }
}

stream_urls: Stream url array for media.

Example

{
    "type": "play",
    "option": {
        "stream_urls": [
            "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
        ]
    }
}

Queue Join

Join to the queue.

Parameters

{
    "type": "queue_join",
    "option": {
        "queue_id": "<string>"
    }
}

queue_id: Target queue id.

Example

{
    "type": "queue_join",
    "option": {
        "queue_id": "99bf739a-932f-433c-b1bf-103d33d7e9bb"
    }
}

Recording Start

Starts the call recording.

Parameters

{
    "type": "recording_start"
    "option": {
        "format": "<string>",
        "end_of_silence": <integer>,
        "end_of_key": "<string>",
        "duration": <integer>,
        "beep_start": <boolean>
    }
}

format: Format to encode audio in. wav, mp3, ogg.
end_of_silence: Maximum duration of silence, in seconds. 0 for no limit.
end_of_key: DTMF input to terminate recording. none, any, *, #.
duration: Maximum duration of the recording, in seconds. 0 for no limit.
beep_start: Play beep when recording begins

Example

{
    "type": "recording_start",
    "option": {
        "format": "wav"
    }
}

Recording Stop

Stops the call recording.

Parameters

{
    "type": "recording_stop"
}

Example

{
    "type": "recording_stop"
}

Sleep

Sleep the call.

Parameters

{
    "type": "sleep",
    "option": {
        "duration": <number>
    }
}

duration: Sleep duration(ms).

Stream Echo

Echoing the RTP stream including the digits receive.

Parameters

{
    "type": "stream_echo",
    "option": {
        "duration": <number>
    }
}

duration: Echo duration. ms.

Example

{
    "type": "stream_echo"
    "option": {
        "duration": 10000
    }
}

Talk

Text to speech. SSML(https://www.w3.org/TR/speech-synthesis/) supported.

Parameters

{
    "type": "talk",
    "option": {
        "text": "<string>",
        "gender": "<string>",
        "language": "<string>",
        "digits_handle": "<string>"
    }
}

text: Text to speech. SSML(https://cloud.google.com/text-to-speech/docs/ssml) supported.
gender: male/female/neutral.
language: Specifies the language. The value may contain a lowercase, two-letter language code (for example, en), or the language code and uppercase country/region (for example, en-US).
digits_handle: See detail here.

Digits handle

Type	Description
next	If digits received in talk, move the action to the next.

Example

{
    "type": "talk",
    "option": {
        "text": "Hello. Welcome to voipbin. This is test message. Please enjoy the voipbin service. Thank you. Bye",
        "gender": "female",
        "language": "en-US"
    }
}

Transcribe recording

Transcribe the call’s recordings.

Parameters

{
    "type": "transcribe_recording"
    "option": {
        "language": "<string>"
    }
}

language: Specifies the language. BCP47 format.

Example

{
    "type": "transcribe_recording"
    "option": {
        "language": "en-US"
    }
}

Transcribe start

Start the STT(Speech to text) transcribe in realtime.

Parameters

{
    "type": "transcribe_start",
    "option": {
        "language": "<string>",
    }
}

language: Specifies the language. BCP47 format. The value may contain a lowercase, two-letter language code (for example, en), or the language code and uppercase country/region (for example, en-US).

Example

{
    "type": "transcribe_start",
    "option": {
        "language": "en-US",
    }
}

Transcribe stop

Stop the transcribe talk in realtime.

Parameters

{
    "type": "transcribe_stop"
}

Example

{
    "type": "transcribe_stop"
}

Variable Set

Stop the transcribe talk in realtime.

Parameters

{
    "type": "variable_set"
    "option": {
        "key": "<string>",
        "value": "<string>"
    }
}

key: Variable name.
value” Varialbe value.

Example

{
    "type": "variable_set"
    "option": {
        "key": "Provider name",
        "value": "voipbin"
    }
}

Webhook send

Send a webhook.

Parameters

{
    "type": "webhook_send"
    "option": {
        "sync": boolean,
        "uri": "<string>",
        "method": "<string>",
        "data_type": "<string>",
        "data": "<string>"
    }
}

sync: If this set to true, waits until this action done.
uri: Destination uri.
method: Send method. POST/GET/PUST/DELETE/…
data_type: Data’s type. application/json, …
data: Data string. Variable can be used.

Example

{
    "type": "webhook_send",
    "option": {
        "sync": true,
        "uri": "https://test.com",
        "method": "POST",
        "data_type": "application/json",
        "data": "{\"destination_number\": \"${voipbin.call.destination.target}\", \"source_number\": \"${voipbin.call.source.target}\"}"
    }
}

Actvieflow

Activeflow

{
    "id": "<string>",
    "flow_id": "<string>",
    "reference_type": "<string>",
    "reference_id": "<string>",
    "current_action": {
        ...
    },
    "forward_action_id": "<string>",
    "actions": [
        ...
    ],
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id: Activeflow’s ID.
flow_id: Based flow id.
reference_type: Referenced resource type. See detail here.
reference_id: Referenced resource’s ID.
current_action: Currently executing action. See detail here
forward_action_id: Forward action ID. This action_id will be executed in the next action execution.
actions: List of actions. See detail here.

Example

{
    "type": "activeflow_created",
    "data": {
        "id": "7daa1750-f0a1-4674-a266-b95a68b27b7c",
        "flow_id": "d157ce07-0360-4cad-9007-c8ab89fccf9c",
        "reference_type": "call",
        "reference_id": "8c0c92c8-b5e6-42b2-80f3-5785b639eb3a",
        "current_action": {
            "id": "00000000-0000-0000-0000-000000000001",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": ""
        },
        "forward_action_id": "00000000-0000-0000-0000-000000000000",
        "actions": [
            {
                "id": "df25724f-e308-4c89-9325-cf56cd09249e",
                "next_id": "00000000-0000-0000-0000-000000000000",
                "type": "answer"
            },
            {
                "id": "2e7ec294-fc66-4039-8446-6590b82ed54f",
                "next_id": "00000000-0000-0000-0000-000000000000",
                "type": "talk",
                "option": {
                    "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                    "gender": "female",
                    "language": "en-US"
                }
            }
        ],
        "tm_create": "2022-04-10 09:06:12.332217",
        "tm_update": "2022-04-10 09:06:12.332217",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

Reference type

Represent referenced resource’s type.

type	Description
call	Call resource reference.
message	Message resource reference.

Tutorial basic

Get list of flows

Gets the list of registered flows.

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/flows?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM'

{
    "result": [
        {
            "id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
            "name": "default flow",
            "detail": "default flow for voipbin incoming calls",
            "actions": [
                {
                    "id": "b34aa8a4-0b30-11eb-8016-1f5bc75b1c04",
                    "type": "play",
                    "option": {
                        "stream_url": [
                            "https://github.com/pchero/asterisk-medias/raw/master/voipbin/welcome.wav"
                        ]
                    }
                },
                {
                    "id": "57a3dcd2-0b2b-11eb-94a6-a7129b64693c",
                    "type": "play",
                    "option": {
                        "stream_url": [
                            "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                        ]
                    }
                }
            ],
            "tm_create": "2020-10-11 01:00:00.000001",
            "tm_update": "",
            "tm_delete": ""
        },
        {
            "id": "af9dae94-ef07-11ea-a101-8f52e568f39b",
            "name": "test flow",
            "detail": "manual flow test",
            "actions": [
                {
                    "id": "00000000-0000-0000-0000-000000000000",
                    "type": "echo"
                }
            ],
            "tm_create": "2020-09-04 23:53:14.496918",
            "tm_update": "",
            "tm_delete": ""
        }
    ],
    "next_page_token": "2020-09-04 23:53:14.496918"
}

Get detail of specified flow

Gets the detail of registered flows.

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/flows/decc2634-0b2a-11eb-b38d-87a8f1051188?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM'

{
    "id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
    "name": "default flow",
    "detail": "default flow for voipbin incoming calls",
    "actions": [
        {
            "id": "b34aa8a4-0b30-11eb-8016-1f5bc75b1c04",
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/voipbin/welcome.wav"
                ]
            }
        },
        {
            "id": "57a3dcd2-0b2b-11eb-94a6-a7129b64693c",
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                ]
            }
        }
    ],
    "tm_create": "2020-10-11 01:00:00.000001",
    "tm_update": "",
    "tm_delete": ""
}

Create a flow

Create a new flow for incoming call requests. When the call is comming, this flow will answer the call first, then will speech the welcome text.

$ curl -k --location --request POST 'https://api.voipbin.net/v1.0/flows?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "test flow",
    "detail": "test voipbin flow example",
    "actions": [
        {
            "type": "answer"
        },
        {
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin'\''s service. thank you.",
                "gender": "female",
                "language": "en-US"
            }
        }
    ]
}'

{
    "id": "24013a0e-d15b-4b5e-9a96-04221a8c6a15",
    "name": "test flow",
    "detail": "test voipbin flow example",
    "actions": [
        {
            "id": "9461bda1-54fd-4e27-ab04-4186c6f72830",
            "type": "answer"
        },
        {
            "id": "69af787e-f5fa-4a1b-9d12-f0b43b86dae6",
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                "gender": "female",
                "language": "en-US"
            }
        }
    ],
    "tm_create": "2021-02-04 06:47:01.139361",
    "tm_update": "",
    "tm_delete": ""
}

Update the flow

Update the existed flow with given info. The doesn’t affect to the existed call. The flow changes will be affected only a new calls.

$ curl -k --location --request PUT 'https://api.voipbin.net/v1.0/flows/decc2634-0b2a-11eb-b38d-87a8f1051188?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "test flow update",
    "detail": "test voipbin flow example update",
    "actions": [
        {
            "type": "answer"
        },
        {
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin'\''s service. thank you.",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/voipbin/welcome.wav"
                ]
            }
        },
        {
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                ]
            }
        }
    ]
}'

{
    "id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
    "name": "test flow update",
    "detail": "test voipbin flow example update",
    "actions": [
        {
            "id": "be682498-e57e-41e9-b210-a578f9c044c5",
            "type": "answer"
        },
        {
            "id": "6669bfdd-a7b0-45e6-9a8d-db6bb898159f",
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "id": "099b60c1-7b95-4d69-8cac-df11a992ee11",
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/voipbin/welcome.wav"
                ]
            }
        },
        {
            "id": "89fa5091-a192-4758-8a29-316776ead8fe",
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                ]
            }
        }
    ],
    "tm_create": "2020-10-11 01:00:00.000001",
    "tm_update": "2021-02-05 13:08:56.113036",
    "tm_delete": ""
}

Delete the flow

Delete the existed flow of given flow id. The doesn’t affect to the existed call.

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/flows/af9dae94-ef07-11ea-a101-8f52e568f39b?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM' \

Tutorial scenario

Simple voicemail

Making a outgoing call for forwarding. If call not answered, leave a voicemail.

               Start
                 |
                 |
             Connect(Making an outgoing call for forwarding)
                 |
                 |
             Condition check(check the call's status is Answered)
                 |
                 |
    ------------------------------
    |                            |
condition false               condition true
    |                            |
    |                          Hangup
  Talk(...)
    |
    |
  Beep
    |
    |
 Recording start
    |
    |
  Sleep(30 sec)
    |
    |
  Hangup

{
    "actions": [
        {
            "type": "connect",
            "option": {
                "source": {
                    "type": "tel",
                    "target": "+821021656521"
                },
                "destinations": [
                    {
                        "type": "tel",
                        "target": "+821021546521"
                    }
                ]
            }
        },
        {
            "id": "3746e628-8cc1-4ff4-82fe-194b16b9a10e",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "condition_call_status",
            "option": {
                "status": "progressing",
                "false_target_id": "cfe0e8ea-991c-11ec-b849-d7fc54168fd5"
            }
        },
        {
            "id": "58f859e9-92d8-4b46-8073-722b9c881ae0",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "hangup"
        },
        {
            "id": "cfe0e8ea-991c-11ec-b849-d7fc54168fd5",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "talk",
            "option": {
                "text": "Thank you for your calling. We are busy now. Please leave a message after tone.",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "id": "0a9b6f38-ddcd-448b-80a1-ae47ac0e08aa",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "beep"
        },
        {
            "id": "ad969315-6ac4-4339-b300-566eb6352fea",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "recording_start",
            "option": {
                "beep_start": true
            }
        },
        {
            "id": "8abf3f9d-414c-4a15-aa94-02a799409f48",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "sleep",
            "option": {
                "duration": 10000
            }
        },
        {
            "id": "e4fc5d9e-9fa8-4b3e-ae77-b55b04c1f2d3",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "hangup"
        }
    ]
}

Simple branch

It will get the digits from the call and will execute the branch.

              Start
                |
                |
------------>  Talk("Press 1 for show must go on. Press 2 for bohemian rhapsody. Press 3 for another one bites the dust")
|               |
|               |
|              Digit(DTMF) receive
|               |
|               |
|       -----------------------------------------------
|       |           |                |                |
|     default      "1"              "2"              "3"
|       |           |                |                |
|       |           |                |                |
|       |          Talk(...)        Talk(...)        Talk(...)
|       |           |                |                |
|       |           |                |                |
|       |          Hangup          Hangup           Hangup
|       |
|       |
|      Talk(...)
|       |
----goto(loop 3 times)
        |
        |
       Talk(...)
        |
        |
       Hangup

{
    "actions": [
        {
            "id": "b8781e56-c524-11ec-889f-d37b0dbb7eb8",
            "type": "talk",
            "option": {
                "text": "Hello. This is branch test. Press 1 for show must go on. Press 2 for bohemian rhapsody. Press 3 for another one bites the dust",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "digits_receive",
            "option": {
                "duration": 5000,
                "length": 1
            }
        },
        {
            "type": "branch",
            "option": {
                "default_target_id": "ed9705ca-c524-11ec-a3fb-8feb7731ad45",
                "target_ids": {
                    "1": "c3eb8e62-c524-11ec-94c5-abafec8af561",
                    "2": "dc87123e-c524-11ec-89c6-5fb18da14034",
                    "3": "e70fb030-c524-11ec-b657-ebec72f097ef"
                }
            }
        },
        {
            "id": "c3eb8e62-c524-11ec-94c5-abafec8af561",
            "type": "talk",
            "option": {
                "text": "Empty spaces, what are we living for? Abandoned places, I guess we know the score, on and on. Does anybody know what we are looking for? Another hero, another mindless crime. Behind the curtain, in the pantomime",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "hangup"
        },
        {
            "id": "dc87123e-c524-11ec-89c6-5fb18da14034",
            "type": "talk",
            "option": {
                "text": "Mama, Just killed a man. Put a gun against his head, pulled my trigger. Now he's dead. Mama, life had just begun, But now I've gone and thrown it all away.",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "hangup"
        },
        {
            "id": "e70fb030-c524-11ec-b657-ebec72f097ef",
            "type": "talk",
            "option": {
                "text": "Steve walks warily down the street. With his brim pulled way down low. Ain't no sound but the sound of his feet. Machine guns ready to go. Are you ready hey are you ready for this?",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "hangup"
        },
        {
            "id": "ed9705ca-c524-11ec-a3fb-8feb7731ad45",
            "type": "talk",
            "option": {
                "text": "You didn't choice correct number. Default selected.",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "goto",
            "option": {
                "target_id": "b8781e56-c524-11ec-889f-d37b0dbb7eb8",
                "loop_count": 2
            }
        },
        {
            "type": "talk",
            "option": {
                "text": "Loop over. Hangup the call. Thank you, good bye.",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "hangup"
        }
    ]
}

Simple message send

Send the message to the multiple destinations.

Start
  |
  |
Message send
  |
  |
 End

{
    "actions": [
        {
            "type": "message_send",
            "option": {
                "source": {
                    "type": "tel",
                    "target": "+821100000001"
                },
                "destinations": [
                    {
                        "type": "tel",
                        "target": "+821100000002"
                    },
                    {
                        "type": "tel",
                        "target": "+821100000003"
                    },
                    {
                        "type": "tel",
                        "target": "+821100000004"
                    }
                ],
                "text": "hello, this is test message."
            }
        }
    ]
}

Simple message send and make a new outbound call

Send the message to the destination and start a new outbound call with talk action.

Start
  |
  |
Message send
  |
  |
Call ------------------- Start
  |                        |
  |                        |
 End                      Talk
                           |
                           |
                          End

{
    "actions": [
        {
            "type": "message_send",
            "option": {
                "source": {
                    "type": "tel",
                    "target": "+821100000001"
                },
                "destinations": [
                    {
                        "type": "tel",
                        "target": "+821100000002"
                    }
                ],
                "text": "hello, this is test message."
            },
            {
                "type": "call",
                "option": {
                    "source": {
                        "type": "tel",
                        "target": "+821100000001"
                    },
                    "destinations": [
                        {
                            "type": "tel",
                            "target": "+821100000003"
                        }
                    ],
                    "actions": [
                        {
                            "type": "talk",
                            "option": {
                                "text": "hello, this is test message.",
                                "gender": "female",
                                "language": "en-US"
                            }
                        }
                    ]
                }
            }
        }
    ]
}