Call

Overview

The VoIPBIN call API provides a straightforward and convenient way to develop high-quality call applications in the Cloud. With the VoIPBIN API, developers can leverage familiar web technologies to build scalable and feature-rich call applications, giving them the power to control inbound and outbound call flows using JSON-based VoIPBIN actions. Additionally, the API offers capabilities to record and store inbound or outbound calls, create conference calls, and send text-to-speech messages in multiple languages with different gender and accents.

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.

Protocol

VoIPBIN offers support for various call/video protocols, enabling users to join the same conference room and communicate with one another seamlessly. The flexibility in protocol options ensures efficient and reliable communication between different devices and platforms.

PSTN/Phone Number Format

In the VoIPBIN APIs, all PSTN/Phone numbers must adhere to the +E164 format. This format standardizes the representation of phone numbers to facilitate smooth communication and interoperability across different systems.

Key requirements for phone numbers within the VoIPBIN APIs:

The phone number must have the ‘+’ symbol at the beginning.
The number should not contain any special characters, such as spaces, parentheses, or hyphens.

For example, a US phone number should be represented as +16062067563, and a Korea phone number should be represented as +821021656521.

Extension Number Format

The extension numbers used in the VoIPBIN system can be customized according to specific requirements. However, they must adhere to the following limitation:

Extension numbers should not contain any special characters, such as spaces, parentheses, or hyphens.

The absence of special characters ensures consistent and reliable processing of extension numbers within the VoIPBIN system, promoting smooth communication and interaction.

With the VoIPBIN call API’s robust features and support for various protocols, developers can create versatile and efficient call applications, enabling seamless communication and collaboration for end-users.

Incoming call

The VoIPBin system provides the functionality to receive incoming calls from external parties. This feature allows users to accept and handle incoming calls through their VoIP services. Incoming calls are crucial for various communication applications and call center setups as they enable users to receive inquiries, provide support, and engage with customers, clients, or other users. When an incoming call is received, the VoIPBin system processes the call request and prepares for call handling based on the specified parameters and configurations.

Execution of Call Flow for incoming call

The execution of the call flow for incoming calls involves a simple yet effective sequence of actions:

Call Verification: When an incoming call is received, the VoIPBin system verifies the call’s authenticity and checks for any potential security risks, such as spoofed or fraudulent calls. This verification process ensures that legitimate calls are allowed to proceed.
Determine Call Flow: After successful verification, the system determines the appropriate call flow based on the destination of the incoming call. The call flow includes a set of predefined actions and configurations tailored to handle calls directed to a specific user, department, or interactive voice response (IVR) system.
Execute Call Flow: Once the call flow is determined, the system proceeds to execute it without delay. The call flow actions are triggered in accordance with the predefined configuration for the call destination.
End the Call: After executing the call flow actions, the system initiates the process of ending the call. The call is terminated, and the connection with the external party is disconnected.

By following this streamlined call flow process, the VoIPBin system efficiently handles incoming calls, ensures their secure and verified handling, and executes the appropriate flow actions based on the call destination. After executing the call flow, the system promptly ends the call, completing the call handling process for the incoming call. Customizable flow actions allow users to tailor the call handling process according to their application’s needs, optimizing user experience and call management efficiency.

Outgoing call

The VoIPBin system offers the outgoing call feature, enabling users to initiate calls to external parties through their VoIP services. This feature is commonly used in various communication applications and call center setups to establish connections with customers, clients, or other users outside the organization. To utilize the outgoing call feature, users need to provide the necessary call parameters, such as the destination phone number, caller ID information, and any additional call settings. These parameters are submitted to the VoIPBin system, which then processes the request and attempts to establish a connection with the specified destination.

Execution of Call Flow for outgoing call

Once the outgoing call request is initiated, the VoIPBin system starts the process of connecting to the destination phone number. During this phase, the system waits for the called party to answer the call. The call flow refers to the sequence of actions and events that occur from the moment the call is initiated until it is successfully answered or terminated.

The call flow execution occurs as follows:

Initiation: The user triggers the outgoing call request, providing the necessary call parameters.
Call Setup: The VoIPBin system processes the request and establishes a connection with the destination phone number.
Wait for Call Answer: After the call setup, the system waits for the called party to answer the call. This waiting period involves ringing the called party’s phone and monitoring the call status.
Call Answered: Once the called party answers the outgoing call, the system proceeds to execute the predefined call flow actions.
Flow Actions Execution: The call flow actions are a set of customizable operations that are executed upon call answer. These actions can include call recording, call routing, call analytics, notifications, and post-call actions, among others.

The call flow execution is critical for ensuring a smooth and efficient communication experience. By customizing the flow actions, users can tailor the call handling process to meet the specific requirements of their application or service, enhancing user engagement and overall call management.

Error handling and Termination

During the incoming/outgoing call process, various errors may occur, such as call failures or network issues. The VoIPBin system have robust error handling mechanisms to gracefully manage such situations. In case of a failed call attempt or call rejection, the system log relevant information for further analysis or reporting purposes.

Call concept

The concept of a call in Voipbin departs from the traditional 1:1 call model. Here’s an overview:

In Voipbin, a call includes source, destination, and additional metadata. Moreover, the call can be associated with multiple other calls, creating a dynamic journey that goes beyond the standard 1:1 connection. Envision a call’s trajectory as it connects to an agent and then diverges to another destination.

In Voipbin, the conventional call scenario A -> B is delineated by two distinct calls:

A            Voipbin            B
|<-- Call 1 --->|               |
|               |<--- Call 2 -->|
|<-----RTP----->|<-----RTP----->|

Comparison: Traditional Call Concept vs Voipbin Call Concept

Traditional Call Concept

Follows a 1:1 model where a call is a direct connection between a source and a destination.
Typically involves a straightforward flow from the caller to the recipient.
Limited in handling complex call journeys or interactions with multiple parties.

Voipbin Call Concept

Deviates from the traditional 1:1 model, allowing for more intricate call structures.
Encompasses source, destination, and additional metadata in a call.
Permits connections to multiple other calls, creating dynamic call journeys.
Visualizes a call’s path, which may involve connecting to an agent and branching to additional destinations.

In summary, while the traditional call concept adheres to a simple point-to-point model, the Voipbin call concept introduces a more flexible and multifaceted approach, accommodating diverse call scenarios and interactions.

Transfer

CPaaS, or Communications Platform as a Service, is a cloud-based technology that allows developers to add real-time communication features to their applications, such as voice and messaging capabilities. Call transfer is a common feature in CPaaS that allows an ongoing phone call to be transferred from one person to another, or from one device to another, without disrupting the conversation.

There are two main types of call transfer in CPaaS: blind transfer and attended transfer.

In both types of call transfer, the transfer can be done manually by the person initiating the transfer, or it can be automated using CPaaS software. Automated transfer is typically done using rules-based routing, which determines the appropriate person or device to transfer the call to based on predefined rules or criteria.

Call transfer is just one of many features available in CPaaS technology, which can help improve call handling, reduce call times, and improve overall customer service.

Attended Transfer

Attended transfer, also known as consultative transfer, involves the person initiating the transfer first speaking to the person who will be taking the call. This allows the person initiating the transfer to provide context or information about the caller or the reason for the transfer. Once the person who will be taking the call is ready, the transfer is initiated and the original caller is connected to the new person or device. Attended transfer is commonly used in situations where the person receiving the call may need more information before taking the call, such as when transferring a call to a supervisor or manager.

Caller           VoIPBin        Transferer        Transferee
|                  |                |                |
|    Call in       | Call in        |                |
|    progress      | progress       |                |
|<---------------->|<-------------->|                |
|                  |                |                |
|                  | Send transfer  |                |
|                  | Request        |                |
|                  |<---------------|                |
|                  |                |                |
|                  | Dial           |                |
|                  |-------------------------------->|
|                  |                |                |
|   MOH/Mute       |                |                |
|<-----------------|                |                |
|                  |                |                |
|                  |                |    Answer      |
|                  |<--------------------------------|
|                  |                |                |
|                  | Call in        |                |
|                  | progress       |                |
|                  |<-------------->|                |
|                  |                |                |
|                  |                | Call in        |
|                  |                | progress       |
|                  |<------------------------------->|
|                  |                |                |
|                  | Hangup         |                |
|                  |<---------------|                |
|                  |                |                |
|  MOH off/Unmute  |                |                |
|<-----------------|                |                |
|                  |                |                |
|    Call in       |                |                |
|    progress      |                |                |
|<---------------->|                |                |

The Caller initiates a call to the VoIPBin, and the call is in progress with transferer.
The Transferer, who is already on a call, decides to transfer the Caller to the Transferee.
The Transferer sends a transfer request to the VoIPBin, indicating the Transferee’s number.
The VoIPBin dials to the Transferee.
The VoIPBin puts the Caller on music on hold and mute.
The Transferee answers the call and is connected to the Transferer and talk to each other.
The Transferer drops out of the call.
The VoIPBin turn off the Caller’s Music on hold and the Caller and Transferee can now hear each other.

This is the basic process of an attended transfer using a CPaaS like VoIPBin. It allows for seamless communication between parties and can help businesses manage their incoming calls more efficiently.

Groupcall

The Groupcall feature in Voipbin is a blast calling functionality that enables team members to communicate in real-time. When a Group Call is initiated, an alert is sent to all team members, allowing them to join the call with a single click. The feature uses VoIP technology to enable high-quality audio communication and offers benefits such as increased productivity, improved collaboration, and enhanced connectivity.

Ringall

Ringall send the dial request to the all of destinations.

The ringall ring method is a way to make calls to multiple destinations simultaneously. When you initiate a groupcall using the ringall method, VoIPBin will place calls to all of the destinations on your list at once. This means that each destination’s phone will start ringing simultaneously, and the person who answers first will begin executing the call flow specified for that groupcall, while all other destinations that have not yet been answered will be hung up immediately. This ensures that only one call is active at a time and the call flow is executed by the person who answered first.

Client           VoIPBin        Destination-1    Destination-2
|                  |                |                |
|    Groupcall     |                |                |
|    request       |                |                |
|----------------->|                |                |
|                  |                |                |
|                  | Dial           |                |
|                  |--------------->|                |
|                  |                |                |
|                  | Dial           |                |
|                  |-------------------------------->|
|                  |                |                |
|                  |                |         Answer |
|                  |<--------------------------------|
|                  |                |                |
|                  | Cancel         |                |
|                  |--------------->|                |

The diagram shows the sequence of events for a Group Call request in VoIPBin with two destination endpoints, Destination-1 and Destination-2. * The Client initiates the Group Call request by sending a request message to the VoIPBin server. * The server then sends a Dial message to Destination-1 and Destination-2 to establish the call. * After Destination-2 answers the call, it sends an Answer message back to the server. * The VoIPBin cancels the call to Destination-1 by sending a Cancel message to Destination-1.

Linear

The linear ring method is a way to call a list of destinations one by one, in a specific order.

When you initiate a groupcall using the linear method, VoIPBin will call the first destination on your list. If that destination does not answer, VoIPBin will move on to the next destination on the list and call it instead. This process will continue until one of the destinations answers the call, at which point the call flow specified for the groupcall will be executed. If all of the destinations on the list have been called and none of them have answered, the call will end without any further action.

The linear method is useful when you want to call a list of destinations in a specific order and don’t want to simultaneously ring all destinations at once.

For example, you might use the linear method for a sales team to call potential clients one by one, in a specific order based on priority.

groupcall1            destinationA       destinationB        destinationC
    |----- ring ---------->|                   |                   |
    |<---- no answer ------|                   |                   |
    |                      |                   |                   |
    |----- ring ------------------------------>|                   |
    |<---- no answer --------------------------|                   |
    |                      |                   |                   |
    |----- ring -------------------------------------------------->|
    |<---- answer -------------------------------------------------|

Nested groupcall

A nested groupcall is a groupcall that is included as one of the destinations in another groupcall. When a groupcall with a nested groupcall is initiated, the nested groupcall is also initiated, creating a “nested” groupcall within the main groupcall.

For example, let’s say you have a groupcall with the following list of destinations: Destination A, Destination B, and Destination C. Destination C is a nested groupcall that includes its own list of destinations: Destination X and Destination Y.

When you initiate the main groupcall, VoIPBin will begin calling Destination A and Destination B simultaneously according to the ring method you’ve specified (either ringall or linear). When it reaches Destination C, the nested groupcall is initiated and VoIPBin will begin calling Destination X and Destination Y according to the ring method specified in the nested groupcall.

Once a destination in the nested groupcall has answered the call, the flow specified for that groupcall is executed. The child groupcall informs the master groupcall that it has answered call. The master groupcall then hangs up any remaining calls that have not yet been answered in the child groupcall, and stops calling the remaining destinations in the main groupcall list.

In VoIPBin, the main groupcall is considered the “master” groupcall and the nested groupcall is considered a “chained” groupcall. Each chained groupcall is assigned a unique ID, and the IDs of all chained groupcalls are stored in a list within the master groupcall. This allows VoIPBin to keep track of all nested groupcalls and their current status within the main call.

It is also possible to have chained groupcalls within chained groupcalls, creating multiple levels of nesting. This means that a nested groupcall can itself include another groupcall as one of its destinations, forming a chain of groupcalls. The nested groupcalls can continue to be chained in a cascading manner, allowing for complex call flows and routing scenarios.

For example, the main groupcall may include a chained groupcall as one of its destinations, and that chained groupcall may, in turn, include another chained groupcall within it. This nesting can extend to multiple levels, providing a highly flexible and customizable approach to call routing and management.

By allowing nested and chained groupcalls, VoIPBin empowers users to design and implement intricate call flows that cater to their specific needs. This functionality opens up possibilities for applications such as multi-level call routing, call forwarding to different departments or teams, and advanced call handling scenarios.

The ability to include nested groupcalls within a main groupcall is a powerful feature that allows for more complex call flows and routing strategies. It can be used, for example, to create more sophisticated call routing trees that can handle a wide range of call scenarios and use cases.

groupcall1            destinationA        destinationB        destinationC
    |----- ring ---------->|                   |       (groupcall destination linear)
    |----- ring ------------------------------>|                   |                         groupcall2        destinationX        destinationY
    |----- ring -------------------------------------------------->|-- start a nested groupcall-->|                 |                   |
    |                      |                   |                                                  |----- ring ----->|                   |
    |                      |                   |                                                  |<-- no answer ---|                   |
    |                      |                   |                                                  |----- ring ------------------------->|
    |                      |                   |                                                  |<-- answer --------------------------|
    |<---------------------------------------- inform that groupcall2 got answered call ----------|
    |----- cancel -------->|                   |
    |----- cancel ---------------------------->|

Struct Call

Call

{
    "id": "<string>",
    "flow_id": "<string>",
    "type": "<string>",
    "master_call_id": "<string>",
    "chained_call_ids": [
        "<string>",
        ...
    ],
    "recording_id": "<string>",
    "recording_ids": [
        "<string>",
        ...
    ],
    "source": {
        ...
    },
    "destination": {
        ...
    },
    "status": "<string>",
    "action": {
        ...
    },
    "direction": "<string>",
    "hangup_by": "<string>",
    "hangup_reason": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_progressing": "<string>",
    "tm_ringing": "<string>",
    "tm_hangup": "<string>"
}

id: Call’s ID.
flow_id: Call’s flow id.
type: Call’s type. See detail here.
master_call_id: Master call’s id. If the master_call_id set, it follows master call’s hangup.
chained_call_ids: List of chained call ids. If the call hangs up, the chained call also will hangup.
recording_id: Shows currently recording id.
recording_ids: List of recording ids.
source: Source address info. See detail here.
destination: Destination address info. See detail here.
status: Call’s status. See detail here.
action: Call’s current action. See detail here.
direction: Call’s direction. See detail here.
hangup_by: Shows call’s hangup end. See detail here.
hangup_reason: Show call’s hangup reason. See detail here.

Example

{
    "id": "d9d32881-12fd-4b19-a6b2-6d5b6b6acf76",
    "flow_id": "4553c074-c88d-49e5-9d47-5c01598ac099",
    "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",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "status": "hangup",
    "action": {
        "id": "0db08d32-b7d7-470d-8bda-9feff0877077",
        "next_id": "00000000-0000-0000-0000-000000000000",
        "type": "talk",
        "option": {
            "text": "Hello. This is Sungtae, nice to meet you. hahaha",
            "gender": "female",
            "language": "en-US"
        },
        "tm_execute": "2022-05-01 15:10:38.785510878"
    },
    "direction": "outgoing",
    "hangup_by": "local",
    "hangup_reason": "normal",
    "tm_create": "2022-05-01 15:10:23.414798",
    "tm_update": "2022-05-01 15:10:44.781000",
    "tm_progressing": "2022-05-01 15:10:38.721000",
    "tm_ringing": "2022-05-01 15:10:26.978000",
    "tm_hangup": "2022-05-01 15:10:44.781000"
}

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.

state diagram

Direction

Call’s direction.

Direction	Description
incoming	The call was coming from the outside of VoIPBIN.
outgoing	The call was generated by 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.
noanswer	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).
amd	Hangup caused by the action type amd. The call’s amd action result hung up the call.

Struct Groupcall

Groupcall

{
    "id": "<string>",
    "customer_id": "<string>",
    "source": {
        ...
    },
    "destinations": [
        {
            ...
        },
        ...
    ],
    "ring_method": "<string>",
    "answer_method": "<string>",
    "answer_call_id": "<string>",
    "call_ids": [
       "<string>",
       ...
    ],
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id: Groupcall’s ID.
customer_id: Customer’s ID
source: Source address info. See detail here.
destinations: List of destination addresses info. See detail here.
ring_method: Ring method. See detail here
answer_method: Answering method. See detail here
answer_call_id: Represents answered call id.
call_ids: List of created call ids.

Example

{
    "id": "d8596b14-4d8e-4a86-afde-642b46d59ac7",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "source": {
        "type": "tel",
        "target": "+821028286521",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "destinations": [
        {
            "type": "endpoint",
            "target": "test11@test",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        {
            "type": "endpoint",
            "target": "test12@test",
            "target_name": "",
            "name": "",
            "detail": ""
        }
    ],
    "ring_method": "",
    "answer_method": "",
    "answer_call_id": "00000000-0000-0000-0000-000000000000",
    "call_ids": [
        "3c77eb43-2098-4890-bb6c-5af0707ba4a6"
    ],
    "tm_create": "2023-04-21 15:33:28.569053",
    "tm_update": "9999-01-01 00:00:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Ring method

Groupcall’s ringing method.

Type	Description
ring_all	Make a call to the all destinations at once.
linear	Make a call to the destination one-by-one in a linear.

Answer method

Call’s status.

Type	Description
hangup_others	Hang up the other calls.

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"
        },
        "destinations": [
            {
                "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"
    },
    "destinations": [
        {
            "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"
    },
    "destinations": [
        {
            "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 digits_send

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

{
    "source": {
        "type": "tel",
        "target": "+821028286521"
    },
    "destinations": [
        {
            "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": ""
    }
]

Simple outbound call with Branch

Making an outbound call with brach. 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 2 times)
        |
        |
       Talk(...)
        |
        |
       Hangup

$ curl --location --request POST 'https://api.voipbin.net/v1.0/calls?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lciI6IntcImlkXCI6XCI1ZTRhMDY4MC04MDRlLTExZWMtODQ3Ny0yZmVhNTk2OGQ4NWJcIixcInVzZXJuYW1lXCI6XCJhZG1pblwiLFwibmFtZVwiOlwiYWRtaW5cIixcImRldGFpbFwiOlwiYWRtaW4gYWNjb3VudFwiLFwid2ViaG9va19tZXRob2RcIjpcIlBPU1RcIixcIndlYmhvb2tfdXJpXCI6XCJodHRwczovL2VueDM4NTN6M2pnMnEueC5waXBlZHJlYW0ubmV0L1wiLFwicGVybWlzc2lvbl9pZHNcIjpbXCIwMzc5NmUxNC03Y2I0LTExZWMtOWRiYS1lNzIwMjNlZmQxYzZcIl0sXCJ0bV9jcmVhdGVcIjpcIjIwMjItMDItMDEgMDA6MDA6MDAuMDAwMDAwXCIsXCJ0bV91cGRhdGVcIjpcIjIwMjItMDQtMTQgMDE6Mjg6NDYuNDU0ODk3XCIsXCJ0bV9kZWxldGVcIjpcIjk5OTktMDEtMDEgMDA6MDA6MDAuMDAwMDAwXCJ9IiwiZXhwIjoxNjUyMjkwNDYyfQ.-jaqJyjISxKmyDxRiFYopD0FA8vlZ_jJ1Sd9mqxCun0' \
--header 'Content-Type: application/json' \
--header 'Cookie: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lciI6IntcImlkXCI6XCI1ZTRhMDY4MC04MDRlLTExZWMtODQ3Ny0yZmVhNTk2OGQ4NWJcIixcInVzZXJuYW1lXCI6XCJhZG1pblwiLFwibmFtZVwiOlwiYWRtaW5cIixcImRldGFpbFwiOlwiYWRtaW4gYWNjb3VudFwiLFwid2ViaG9va19tZXRob2RcIjpcIlBPU1RcIixcIndlYmhvb2tfdXJpXCI6XCJodHRwczovL2VueDM4NTN6M2pnMnEueC5waXBlZHJlYW0ubmV0L1wiLFwicGVybWlzc2lvbl9pZHNcIjpbXCIwMzc5NmUxNC03Y2I0LTExZWMtOWRiYS1lNzIwMjNlZmQxYzZcIl0sXCJ0bV9jcmVhdGVcIjpcIjIwMjItMDItMDEgMDA6MDA6MDAuMDAwMDAwXCIsXCJ0bV91cGRhdGVcIjpcIjIwMjItMDQtMTQgMDE6Mjg6NDYuNDU0ODk3XCIsXCJ0bV9kZWxldGVcIjpcIjk5OTktMDEtMDEgMDA6MDA6MDAuMDAwMDAwXCJ9IiwiZXhwIjoxNjUyMjkwNDYyfQ.-jaqJyjISxKmyDxRiFYopD0FA8vlZ_jJ1Sd9mqxCun0' \
--data-raw '{
    "source": {
        "type": "tel",
        "target": "+821028286521"
    },
    "destinations": [
        {
            "type": "tel",
            "target": "+821021656521"
        }
    ],
    "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"
        }
    ]
}'

[
    {
        "id": "77517719-ffb9-4583-ba44-737ba991d685",
        "flow_id": "c0827e56-41ef-4fa1-9da0-a8a36fbb76c4",
        "confbridge_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",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "destination": {
            "type": "tel",
            "target": "+821021656521",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "status": "dialing",
        "action": {
            "id": "00000000-0000-0000-0000-000000000001",
            "type": ""
        },
        "direction": "outgoing",
        "hangup_by": "",
        "hangup_reason": "",
        "tm_create": "2022-02-24 02:08:14.469405",
        "tm_update": "9999-01-01 00:00:00.000000",
        "tm_progressing": "9999-01-01 00:00:00.000000",
        "tm_ringing": "9999-01-01 00:00:00.000000",
        "tm_hangup": "9999-01-01 00:00:00.000000"
    }
]

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

Make a groupcall

Make a groupcall to the multiple destinations.

$ curl --location --request POST 'https://api.voipbin.net/v1.0/groupcalls?token=eyJhbGcslkj' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "source": {
            "type": "tel",
            "target": "+821100000001"
        },
        "destinations": [
            {
                "type": "endpoint",
                "target": "test11@test"
            },
            {
                "type": "endpoint",
                "target": "test12@test"
            }
        ],
        "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"
                }
            }
        ]
    }'

{
    "id": "d8596b14-4d8e-4a86-afde-642b46d59ac7",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "source": {
        "type": "tel",
        "target": "+821028286521",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "destinations": [
        {
            "type": "endpoint",
            "target": "test11@test",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        {
            "type": "endpoint",
            "target": "test12@test",
            "target_name": "",
            "name": "",
            "detail": ""
        }
    ],
    "ring_method": "",
    "answer_method": "",
    "answer_call_id": "00000000-0000-0000-0000-000000000000",
    "call_ids": [
        "3c77eb43-2098-4890-bb6c-5af0707ba4a6",
        "2bcaff64-e05d-11ed-84a6-133172844032"
    ],
    "tm_create": "2023-04-21 15:33:28.569053",
    "tm_update": "9999-01-01 00:00:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Call

Overview

Protocol

PSTN/Phone Number Format

Extension Number Format

Incoming call

Execution of Call Flow for incoming call

Outgoing call

Execution of Call Flow for outgoing call

Error handling and Termination

Call concept

Comparison: Traditional Call Concept vs Voipbin Call Concept

Transfer

Blind Transfer

Attended Transfer

Groupcall

Ringall

Linear

Nested groupcall

Struct Call

Call

Example

Type

Status

Direction

Hangup by

Hangup reason

Struct Groupcall

Groupcall

Example

Ring method

Answer method

Tutorial

Simple outbound call with TTS

Simple outbound call with media file play

Simple outbound call with TTS and connect

Simple outbound call with talk and digits_send

Simple outbound call with Branch

Get call list

Get specific call

Make a groupcall