Call

Overview

The VoIPBIN call API is the easiest way to build high-quality call application in the Cloud.

With the VoIPBIN API you can:

  • Build apps that scale with the web technologies you are already using.
  • Control the flow of inbound and outbound calls in JSON with VoIPBIN’s actions.
  • Record and store inbound or outbound calls.
  • Create conference calls.
  • Send text-to-speech messages in 50 languages with different gender and accents.

PSTN/Phone number format

Within the VoIPBIN APIs, all PSTN/Phone numbers are in +E164 format. This means that numbers:

  • The number has to set the ‘+’ at the front.
  • Contain no special characters, such as space, () or -.

For example, a US number would have the format +16062067563. A Korea number would have the format +821021656521.

Extension number format

Extension numbers can be anything with the below limitation.

  • Contain no special characters, such as space, () or -.

Tutorial

Simple outbound call with TTS

Making an outbound call with TTS(Text-to-Speech) action. When the destination answer the call, it will speak the given text message.

$ curl --location --request POST 'https://api.voipbin.net/v1.0/calls?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDcyNjM5MjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.py7AwXIO0ZNBWSS1PN-05L9oYEREjGgbkkE6CcVyuzw' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "source": {
            "type": "tel",
            "target": "+821028286521"
        },
        "destination": {
            "type": "tel",
            "target": "+821021656521"
        },
        "actions": [
            {
                "type": "talk",
                "option": {
                    "text": "hello. welcome to voipbin. This is test message. This audio file is generated dynamically by the tts module. Please enjoy the voipbin service. Thank you. Bye",
                    "gender": "female",
                    "language": "en-US"
                }
            }
        ]
    }'

Simple outbound call with media file play

Making an outbound call with media file play action. When the destination answer the call, it will play the given media file.

$ curl --location --request POST 'https://api.voipbin.net/v1.0/calls?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM' \
--header 'Content-Type: application/json' \
--data-raw '{
    "source": {
        "type": "tel",
        "target": "+821028286521"
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521"
    },
    "actions": [
        {
            "type": "play",
            "option": {
                "stream_urls": [
                    "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                ]
            }
        }
    ]
}'

{
    "id": "a023bfa8-1091-4e94-8eaa-7f01fbecc71a",
    "user_id": 1,
    "flow_id": "f089791a-ac78-4ea0-be88-8a8e131f9fc5",
    "conf_id": "00000000-0000-0000-0000-000000000000",
    "type": "flow",
    "master_call_id": "00000000-0000-0000-0000-000000000000",
    "chained_call_ids": [],
    "recording_id": "00000000-0000-0000-0000-000000000000",
    "recording_ids": [],
    "source": {
        "type": "tel",
        "target": "+821028286521",
        "name": ""
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521",
        "name": ""
    },
    "status": "dialing",
    "direction": "outgoing",
    "hangup_by": "",
    "hangup_reason": "",
    "tm_create": "2021-02-04 04:44:20.904662",
    "tm_update": "",
    "tm_progressing": "",
    "tm_ringing": "",
    "tm_hangup": ""
}

Simple outbound call with TTS and connect

Making an outbound call with TTS(Text-to-Speech) and connect to other destination.

$ curl -k --location --request POST 'https://api.voipbin.net/v1.0/calls?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM' \
--header 'Content-Type: application/json' \
--header 'Cookie: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM' \
--data-raw '{
    "source": {
        "type": "tel",
        "target": "+821021656521"
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521"
    },
    "actions": [
        {
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. This audio file is generated dynamically by the tts module. Please enjoy the voipbin service.",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "connect",
            "option": {
                "source": {
                    "type": "tel",
                    "target": "+821021656521"
                },
                "destinations": [
                    {
                        "type": "tel",
                        "target": "+821043126521"
                    }
                ]
            }
        }
    ]
}'

{
    "id": "9f6265bc-6b59-4e80-a906-2679aca11455",
    "user_id": 1,
    "flow_id": "d665fbc0-6dd8-44bc-99ea-2ae54bc59428",
    "conf_id": "00000000-0000-0000-0000-000000000000",
    "type": "flow",
    "master_call_id": "00000000-0000-0000-0000-000000000000",
    "chained_call_ids": [],
    "recording_id": "00000000-0000-0000-0000-000000000000",
    "recording_ids": [],
    "source": {
        "type": "tel",
        "target": "+821021656521",
        "name": ""
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521",
        "name": ""
    },
    "status": "dialing",
    "direction": "outgoing",
    "hangup_by": "",
    "hangup_reason": "",
    "tm_create": "2021-02-06 09:52:49.941865",
    "tm_update": "",
    "tm_progressing": "",
    "tm_ringing": "",
    "tm_hangup": ""
}

Simple outbound call with talk and dtmf_send

Making an outbound call. After answer the call, it will play the TTS and then send the DTMFs.

{
    "source": {
        "type": "tel",
        "target": "+821028286521"
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521"
    },
    "actions": [
        {
            "type": "talk",
            "option": {
                "text": "This is dtmf send test call. Please wait.",
                "gender": "female",
                "language": "en-US"
            }
        },
        {
            "type": "dtmf_send",
            "option": {
                "dtmfs": "1234567890",
                "duration": 500,
                "interval": 500
            }
        },
        {
            "type": "talk",
            "option": {
                "text": "Thank you. DTMF send test has done.",
                "gender": "female",
                "language": "en-US"
            }
        }
    ]
}

{
    "id": "d7520a58-0b07-4dd7-ab72-a4e2d1979ec0",
    "user_id": 1,
    "flow_id": "0f4bd9bc-9df5-4a5b-9465-2189822a3019",
    "conf_id": "00000000-0000-0000-0000-000000000000",
    "type": "flow",
    "master_call_id": "00000000-0000-0000-0000-000000000000",
    "chained_call_ids": [],
    "recording_id": "00000000-0000-0000-0000-000000000000",
    "recording_ids": [],
    "source": {
        "type": "tel",
        "target": "+821028286521",
        "name": ""
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521",
        "name": ""
    },
    "status": "dialing",
    "direction": "outgoing",
    "hangup_by": "",
    "hangup_reason": "",
    "tm_create": "2021-02-08 03:59:33.281711",
    "tm_update": "",
    "tm_progressing": "",
    "tm_ringing": "",
    "tm_hangup": ""
}

Get call list

Getting a list of calls.

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

{
    "result": [
        {
            "id": "9a7857ca-73ba-4000-8101-c47d3b48f9d1",
            "user_id": 1,
            "flow_id": "00000000-0000-0000-0000-000000000000",
            "conf_id": "00000000-0000-0000-0000-000000000000",
            "type": "sip-service",
            "master_call_id": "00000000-0000-0000-0000-000000000000",
            "chained_call_ids": [],
            "recording_id": "00000000-0000-0000-0000-000000000000",
            "recording_ids": [],
            "source": {
                "type": "tel",
                "target": "109",
                "name": "109"
            },
            "destination": {
                "type": "tel",
                "target": "972595897084",
                "name": ""
            },
            "status": "hangup",
            "direction": "incoming",
            "hangup_by": "remote",
            "hangup_reason": "normal",
            "tm_create": "2021-02-06 09:47:10.018000",
            "tm_update": "2021-02-06 09:48:14.630000",
            "tm_progressing": "2021-02-06 09:47:10.626000",
            "tm_ringing": "",
            "tm_hangup": "2021-02-06 09:48:14.630000"
        },
        ...
    ],
    "next_page_token": "2021-02-06 08:54:38.361000"
}

Get specific call

Getting a given call uuid’s call info.

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/calls/f457951b-9918-44af-a834-2216b1cc31bc?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NDIyMjcsInVzZXIiOnsiaWQiOjEsInBlcm1pc3Npb24iOjEsInVzZXJuYW1lIjoiYWRtaW4ifX0.OWJihCRfaRtQKtV9fmfgxtpMk6TMQQtq9cSefln7vxM'

{
    "id": "f457951b-9918-44af-a834-2216b1cc31bc",
    "user_id": 1,
    "flow_id": "246aeabe-fab5-4a1b-8e98-852b50e89dd7",
    "conf_id": "00000000-0000-0000-0000-000000000000",
    "type": "flow",
    "master_call_id": "00000000-0000-0000-0000-000000000000",
    "chained_call_ids": [],
    "recording_id": "00000000-0000-0000-0000-000000000000",
    "recording_ids": [
        "142e8ef8-392c-4514-abf0-8656da5d2fdf"
    ],
    "source": {
        "type": "tel",
        "target": "+821028286521",
        "name": ""
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521",
        "name": ""
    },
    "status": "hangup",
    "direction": "outgoing",
    "hangup_by": "remote",
    "hangup_reason": "normal",
    "tm_create": "2021-01-29 03:17:54.349101",
    "tm_update": "2021-01-29 03:18:22.131000",
    "tm_progressing": "2021-01-29 03:18:07.810000",
    "tm_ringing": "2021-01-29 03:17:55.392000",
    "tm_hangup": "2021-01-29 03:18:22.131000"
}

Struct

Type

Call’s type.

Type Description
flow Executing the call-flow
conference Conference call.
sip-service sip-service call. Will execute the corresponding the pre-defined sip-service by the destination.

Status

Call’s status.

Status Description
dialing The call is created. We are dialing to the destination.
ringing The destination has confirmed that the call is ringng.
progressing The call has answered. The both endpoints are talking to each other.
terminating The call is terminating.
canceling The call originator is canceling the call.
hangup The call has been completed.

Direction

Call’s direction.

Direction Description
incoming Call is coming from outside from voipbin.
outgoing Call is generating form the voipbin.

Hangup by

The Hangup by shows which endpoint sent the hangup request first.

hangup by Description
remote The remote end hangup the call first.
local The local end hangup the call first.

Hangup reason

Shows why the call was hungup.

Reason Description
normal The call has ended after answer.
failed The call attempt(signal) was not reached to the phone network.
busy The destination is on the line with another caller.
cancel Call was cancelled by the originator before it was answered.
timeout Call reached max call duration after it was answered.
unanswer Destination didn’t answer until destination’s timeout.
dialout The call reached dialing timeout before it was answered. This timeout is fired by our time out(outgoing call).

Address

Defines target(source/destination) address.

{
    "type": "<string>",
    "target": "<string>",
    "name": "<string>"
}
  • type: Address type.
  • target: Target address.
  • name: Target name.

Address type

Type Description
sip SIP type address.
tel Telephone type address.

Action

AMD

Answering machine detection.

Parameters

{
    "type": "amd",
    "option": {
        "machine_handle": "<string>",
        "async": <boolean>
    }
}
  • machine_handle: hangup,delay,continue if the machine answered a call.
  • async: if it’s false, the call flow will be stop until amd done.

Example

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

Answer

Answer the call

Parameters

{
    "type": "answer"
}

Example

{
    "type": "answer"
}

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": [
            {...},
            ...
        ]
        "unchained": <boolean>
    }
}
  • source: Source address.
  • destinations: Destination addresses.
  • unchained: If it sets to false, connected destination calls will be hungup when the master call is hangup. Default false.

Example

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

DTMF Receive

Receives the DTMFs for given duration or numbers.

Parameters

{
    "type": "dtmf_receive",
    "option": {
        "max_number_key": <number>,
        "duration": <number>,
        "finish_on_key": "<string>"
    }
}
  • max_number_key: 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.
  • 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.
  • finish_on_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": "dtmf_receive",
    "option": {
        "max_number_key": 3,
        "duration": 10000,
        "finish_on_key": "#"
    }
}

DTMF Send

Sends the DTMFs with given duration and interval.

Parameters

{
    "type": "dtmf_send",
    "option": {
        "dtmfs": "<string>",
        "duration": <number>,
        "interval": <number>
    }
}
  • dtmfs: The dtmf 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.
  • finish_on_key: Interval between sending keys in milliseconds. Allowed values: Between 0 and 5000.

Example

{
    "type": "dtmf_send",
    "option": {
        "dtmfs": "1234567890",
        "duration": 500,
        "interval": 500
    }
},

Echo

Echoing the call.

Parameters

{
    "type": "echo",
    "option": {
        "duration": <integer>,
        "dtmf": <boolean>
    }
}
  • duration: Echo duration. ms.
  • dtmf: Sending back the DTMF.

Example

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

Hangup

Hangup the call.

Parameters

{
    "type": "hangup"
}

Example

{
    "type": "hangup"
}

Patch

Patch the next flow from the remote.

Parameters

{
    "type": "patch",
    "option": {
        "event_url": "<string>",
        "event_method": "<string>"
    }
}
  • event_url: The url for flow patching.
  • event_method: The method for flow patching.

Example

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

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

Recording Start

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

Parameters

{
    "type": "recording_stop"
}

Example

{
    "type": "recording_stop"
}

Talk

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

Parameters

{
    "type": "talk",
    "option": {
        "text": "<string>",
        "gender": "<string>",
        "language": "<string>"
    }
}
  • text: Text to speech. SSML(https://cloud.google.com/text-to-speech/docs/ssml) supported.
  • gender: male/female.
  • 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).

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_start

Start the transcribe talk in realtime.

Parameters

{
    "type": "transcribe_start",
    "option": {
        "language": "<string>",
        "webhook_uri": "<string>",
        "webhook_method": "<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).
  • webhook_uri: Target webhook uri.
  • webhook_method: Target webhook method.

Example

{
    "type": "transcribe_start",
    "option": {
        "language": "en-US",
        "webhook_uri": "https://test.com",
        "webhook_method": "POST"
    }
}

Transcribe_stop

Stop the transcribe talk in realtime.

Parameters

{
    "type": "transcribe_stop"
}

Example

{
    "type": "transcribe_stop"
}