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.

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.

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.

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.

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.

POST URL

https://api.teletracker.net/voice/originate

URL Parameters

None

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,
   "result":
   {
      "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.