Developer Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Initiate Voice Call

This endpoint initiates a voice call between two parties: The caller and the callee. It’s a convenient way to implement a click to call solution.

Here’s How it Works

  1. Immediately after you make the API request, we will attempt to dial the caller.
  2. Once the caller answers, we immediately start dialing the callee.
  3. The caller will hear a ringback tone, notifying them that we are attempting to reach the callee.
  4. When the callee answers, both parties can start talking to each other.

What Number Does the Callee See When Their Phone Rings?

  1. If you specify a user_id or pin value of a user on your account, we will use that user’s phone number if they have communication abilities enabled.
  2. If no user is specified, we will attempt to use the account-wide outgoing caller id setting.

How We Associate a Call With a User

In order to associate the call with a user, you must specify the user_id or pin value below. This means that we record the user’s id value with the call data record so that the call shows up in the user’s individual history and in the reports on the account.

Keep in Mind the Following

Caller and callee can be phone numbers, PINs or even ring groups. For example, if you set caller=9999 and callee=4444, we would attempt to call user with PIN 9999 first, then when they answer, we call the user with PIN 4444.

You can mix and match numbers and users as you need: caller=9999 and callee=8884507990 would call user with PIN 9999, and then connect that user with the toll free number (888) 450-7990.

Let’s say you have a ring group with number 100. You could specify caller=9999 and callee=100 which would call the user with PIN 9999, and then connect that user with the ring group.

When you use this endpoint to call two external phone numbers that are not on your account, each leg of the call will separately accrue outgoing minutes against your account since we have placed two external phone calls and joined them together.

API Request

URL Parameters
Request Parameters
Parameter Type Usage Description
caller string Required This needs to be a person. Specify a direct number (cell phone, desk phone) or a PIN to call a user directly.
callee string Required This can be a phone number, another user via PIN, a ring group, or any other dialable destination on your account.
account_id integer Depends Specify the account id explicitly to use when initiating the call. Optional for users. Required for integrators.
user_id integer Optional Manually associate the call with a user. Used when the caller param does not identify a user on your account directly.
pin integer Optional Alternatively, specify the user with the PIN instead of user_id to manually associate this call with a user.
extra object Optional A JSON string containing any key:value pairs that you want to get sent back to you via the Push or RealTime API. See notes for extra data.
Response Body
   "guid": "6f096077-9661-4749-84fa-1191768c1b8d",
   "success": true,
      "caller": "+15045551234",
      "callee": "+15045551235",
      "pin": 1111,
      "creation_date": "2018-04-18T17:41:32.900Z",
      "extraData": { ... },
      "outgoing_id": 35209792,
      "user_id": 190232
Error Code Description
DUPLICATE_QUEUE_ENTRY You have attempted to place a duplicate call in too short a time period. Wait a few seconds and try again.
INVALID_PHONENUMBER One of the phone numbers specified is invalid. Check errorCode for additional info.
INVALID_USER The specified user does not exist on the account.
INVALID_ACCOUNT The account id, if specified, is not valid or you do not have access to it.