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.

_images/flow_overview_non_linear.png

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.

_images/flow_overview_fork.png

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

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

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.

_images/flow_action_call.png

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"
                            }
                        }
                    ]
                }
            }
        }
    ]
}