NAV
JSON

Introduction

Shoutpoint’s Programmable Voice and Messaging API enables you to architect and embed intelligent communications into your application. The service allows you to programmatically make and receive phone calls, create call flows, modify live calls, record calls, manage phone numbers, and send and receive SMS.

Shoutpoint API

Tools Include

Postman Collection

To help our development community, we created a Postman collection which can be used to test the various API methods.

If you are not familiar with Postman, visit Get Postman to learn more. In short, it provides a robust interface for running, testing, documenting, and sharing APIs.

Click the button below to download our collection and have fun! Last Updated on August 17, 2017.

Run in Postman

Overview

Call Flow Loop

Example Response

{  
   "actions":[  
      {  
         "type":"SAY",
         "params":{  
            "text":"Hello, Jill",
            "loop":1
         }
      },
      {  
         "type":"CONFERENCE",
         "params":{  
            "name":"test-conf"
         }
      },
      {  
         "type":"SAY",
         "params":{  
            "text":"You have left the conference. Please rate your experience from 1 to 5."
         }
      },
      {  
         "name":"rating",
         "type":"COLLECT",
         "params":{  
            "num_digits":1,
            "finish_on_key":"pound",
            "timeout":3000
         }
      },
      {  
         "type":"SAY",
         "params":{  
            "text":"Thank you and good bye."
         }
      }
   ]
}

Shoutpoint’s Call Flow Loop allows you to control phone calls using our set of Call Flow Actions. When a call is initiated or received, Shoutpoint will make a request to the URL that you designate to fetch instructions from your server. Your response will determine what to do next with the call.

Multi-Action Processing

Responses can be as simple as a single action.  

Example: SAY “Hello, Jill”.

Or it can be an array of actions that lead the caller through a much more complicated call flow.

Example: SAY “Hello, Jill”, put the caller in a CONFERENCE, wait until the caller leaves the conference (press #), SAY a question, COLLECT a key press, and SAY goodbye, HANGUP.

This combined with our other tools like session data, conditionals, and variables may come as good news to those who have found themselves in ‘callback hell’ while using other services.

Phone Number Configuration

After purchasing and assigning one or more phone numbers to CallFlows via the REST API, you must configure the callback settings for the phone number(s) via Create Call Flow Callback. Once configured, your server will get callback requests to control calls.

How it Works

To learn more about our call flow loop, visit our How It Works pages:

Action Types

All actions have type, params, name and comments properties and can be passed in an array.

Property Description Type Required
type Accepts: COLLECT, CONFERENCE, DETECT, DIAL, GOTO, HANGUP, IF, LABEL, PAUSE, PLAY, QUEUE, RECORD, REDIRECT, REJECT, SAY, SESSIONDATA, SMS, STOP, TRANSFER and WEBHOOK. string Yes
params The parameters for the action type. See below for each type. object No
name A name to give the action. string Conditional
comments An optional string of comments to document the action. string No

Callback Request

When a phone call is received or initiated, or an sms is received, Shoutpoint will send a request to the URL that you designate in your callback configuration. The contents will include the information that we know about the phone call.

The request payload to your callback URL will be a JSON object by default. By setting the content-type in the callback configuration, you can choose to receive JSON, XML, url-encoded form data, or a URL with a query string.

Example Request // Call

{
    "type": "end_call",
    "app_id": "29a471cc-4ada-4249-a7a5-5046464f9887",
    "subaccount_id": 0,
    "call_id": "[email protected]",
    "start_time": "2016-09-20T21:32:28.471Z",
    "api_no": "+17145551212",
    "caller_no": "+19495551212",
    "direction": "inbound",
    "duration": 9763,
    "status": "completed",
    "key_presses": null,
    "last_queue_poll_connect_call": null,
    "custom_data": null,
    "session_data": null,
    "end_time": "2016-09-20T21:32:38.144Z",
    "sip_domain": "1234-56789.accounts.sip.shoutpoint.com",
    "sip_forwarded_for": "192.168.1.1",
    "caller_no_region": "CA",
    "caller_no_country": "US",
    "caller_no_timezone": "America/Los_Angeles",
    "api_no_region": "CA",
    "api_no_country": "US",
    "api_no_timezone": "America/Los_Angeles"
}

Request

Property Description Type When
type Options: init_call, live_call, end_call, sms. string all
app_id The application ID for this request. string all
subaccount_id The Sub Account ID for this request. number all
call_id The ID of the call or SMS. string all
caller_no The phone number of the connected (or far end) call (E.164 format: +17145551212). string all
caller_no_region The two-character region (state) code of the connected call’s phone number. Possibly null. string all
caller_no_country The two-character country code of the connected call’s phone number. Possibly null. string all
caller_no_timezone The time zone of the connected call’s phone number (America/Los_Angeles). Possibly null. Click here for list of time zones. string all
api_no The phone number provisioned to the API (E.164 format: +17145551212). string all
api_no_region The two-character region (state) code of the API phone number. Possibly null. string all
api_no_country The two-character country code of the API phone number. Possibly null. string all
api_no_timezone The time zone of the API phone number (America/Los_Angeles). Possibly null. Click here for list of time zones. string all
start_time The time the call started. date init_call, live_call, end_call, webhook
end_time The time the call ended. date sms, end_call
direction Specifies the direction of the call: inbound or outbound string all
duration The length of the call in milliseconds. long all
status The current call state and progress. Codes: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. string all
key_presses The keys pressed during the request block. array (object) live_call
key_presses[].name The name of the COLLECT action that recorded these digits. Query string converts to “key_presses.{name}={digits}”. string live_call
key_presses[].digits The keys pressed during the COLLECT. string live_call
last_queue_poll_connect_call The last call bridged to this call via a QUEUE poll_connect. object live_call, end_call
last_queue_poll_connect_call.id The bridged call’s ID. string live_call, end_call
last_queue_poll_connect_call.no The bridged call’s phone number. string live_call, end_call
text_message The inbound text message. string sms
custom_data The custom data set in the callback configuration. all
session_data The session_data set in the /Dials/Connect request and/or the DIALS and SESSIONDATA actions. all
is_webhook If true, the request originated from a webhook action. Else, this property is omitted. boolean webhook
event_name The event_name set in the WEBHOOKS action. If not a webhook request, this property is omitted. string webhook
webhook_data The webhook_data set in the WEBHOOKS action. If not a webhook request, this property is omitted. webhook
sip_domain The SIP domain assigned to the application or sub-account. string all
sip_forwarded_for The origin IP address of the SIP request. string all

Example Request // SMS

{
    "type": "sms",
    "app_id": "29a471cc-4ada-4249-a7a5-5046464f9887",
    "subaccount_id": "0",
    "call_id": "[email protected]",
    "start_time": "2016-09-20T21:33:58.790Z",
    "api_no": "+17145551212",
    "caller_no": "+19495551212",
    "duration": 1195,
    "status": "inbound-sms",
    "key_presses": null,
    "last_queue_poll_connect_call": null,
    "custom_data": null,
    "session_data": null,
    "text_message": "Hello",
    "is_webhook": "false",
    "caller_no_region": "CA",
    "caller_no_country": "US",
    "caller_no_timezone": "America/Los_Angeles",
    "api_no_region": "CA",
    "api_no_country": "US",
    "api_no_timezone": "America/Los_Angeles"
}

Callback Response

To control the call, Shoutpoint expects a response with one or more Call Flow Actions.

The response to control the call can be in JSON or CCML. Set the Content-Type header to application/json or application/xml respectively.

A HTTP Status Code other than 2xx will terminate the call.

Response

Parameter Description Type Required
actions An array of Action objects, executed in the order given. string Yes
name An optional name to help identify the response. Example: MainMenu. string No
comments Optional comments to help document this response. string No

Example Response

{  
   "actions":[  
      {  
         "type":"SAY",
         "params":{  
            "text":"Hello, ${sessionData.firstName}. Welcome to our conference.",
            "loop":1
         }
      },
      {  
         "type":"CONFERENCE",
         "params":{  
            "name":"myConference"
         }
      },
      {  
         "type":"SAY",
         "params":{  
            "text":"You have left the conference. This call lasted ${callTime} milliseconds."
         }
      }
   ]
}

Error Handling

If your call fails, you will hear a generic audio error on the phone. For more details, look at your Call Logs. If you require more digging, you can view your Call Flow Logs to get more detail.

A full accounting of all error messages may be found in the Errors section of this reference.

REST API

The Shoutpoint REST API enables you to initiate, modify, and query meta data on phone calls. It also allows you to manage your account, applications, sub accounts, phone numbers, recordings, and callback configurations.

Base URL

All URLs referenced in the documentation have the same base API endpoint, which is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

HTTPS API Endpoint

https://api.shoutpoint.com/v1

Should you require cross-origin resource sharing (CORS) support, we have you covered.

HTTPS API Endpoint // CORS

https://api.shoutpoint.com/CORS/v1

Authentication

The Shoutpoint API is authenticated using either Basic Authentication (username and password) or an API Key. For Account-level requests, use Basic Authentication. For Application-level requests, pass the API Key in a X-API-Key header. Each API method will specify which type of authentication is required.

As a general rule of thumb, Application-level API methods are used for everything related to managing phone numbers, voice, and sms, whereas Account-level requests are used for billing and payments.

To create or modify your credentials, visit the Developer Portal.

Application Sub Accounts

Application Sub Accounts are a way to isolate usage of the api within a single application, including phone numbers, calls, sms, conferences, queues, logs and recordings. Think of them as child-applications under the main application. For example, if your application services multiple users, you might want to give each user its own Sub Account, thereby isolating their usage from your other users. This isolation extends to call behavior, reporting and API methods.

Example Request // Phone Numbers

GET /SubAccounts/{id}/PhoneNumbers

To use a Sub Account, simply prepend a regular API method with /SubAccounts/{id}.

Application Sub Accounts have the expected CRUDing methods.

Example Request // Make Call

POST /SubAccounts/{id}/Dials/Connect

Pagination

Shoutpoint’s API supports pagination and provides a request query to control how pagination will respond to specific methods.

Request Query

Name Description Type Required
page The page number to return. Zero-based index. Default to 0 int No
page_size The number of subaccounts per page. Default to 1000 int No

Response

Parameter Description Type
pagination Information about the request pagination. object
pagination.current_page The page returned. int
pagination.total_pages The number of pages available. int
pagination.total_items The total number of items available. int
pagination.items_per_page The maximum number of items allowed per response. int

Example Response

{  
   "subaccounts": [  
      {  
         "id":0,
         "name":"My First Sub Account"
      }
   ],
   "pagination": {
      "current_page": 0,
      "total_pages": 1,
      "total_items": 1,
      "items_per_page": 10
   }
}

Request

Shoutpoint’s API is organized around REST principles, accepts JSON, and supports the following HTTP Verbs:

To see a list of all supported methods, click here.

Response

All responses will return JSON.

Any 2xx status codes are considered a success.

A table with response codes is included in the documentation with each REST method.

Error Handling

Any non-2xx HTTP status code is considered a request failure.

4xx errors are caused by the developer (for example, “401 Unauthorized” and “404 Not Found”).

5xx errors are caused by exceptions within the Shoutpoint platform. These errors are not caused by the developer and should be reported to Shoutpoint, if possible. It is likely a systematic error that will need to be fixed.

Response

Property Description Type
ref_id A unique identifier for the error. string
status The HTTP status code of the error. integer
code A more detailed error code, often prepended with the status code. For example, 401005. Note: These codes are subject to revision until v1. integer
message A human readable message about the error. string
help Any information that may help resolve this error. string
user_message A diplomatic message that can be shown to the end user. string

Example Response:

{
  "ref_id": "f3749fj290djk29fj239dji9j",
  "status": 400,
  "code": 401005,
  "message": "authentication is possible but has failed ",
  "help": "The request must include the header named X-API-Key.",
  "user_message": "A 3rd-party service could not understand your 
  request. This could be due to submitting invalid data."
}

All API Actions and Methods will inform the developer of success or failure. A full accounting of all error messages may be found in the Errors section of this reference. Also, all Actions and Methods have a Response Codes table which provides a list of specific error messages for that Action or Method.

Session Data

In order to customize your call flows, it is possible to assign unique session data for each call. This data will be returned with the Call Flow Callback Request for the lifetime of the call in the session_data property as a JSON object.

Tools

You can freely read and write to the session_data property through the following ways:

Example Callback Response // Call Flow using Session Data

{  
   "actions":[  
      {  
         "type":"SAY",
         "params":{  
            "text":"This is ${sessionData.doctor} office calling to confirm your appointment on ${sessionData.day}, ${sessionData.month}, ${sessionData.date} at ${sessionData.time}."
         }
      }
   ]
}

Cut Back On Callbacks

You may leverage session_data as a User-Defined Variable while building your call flows using our JSON Actions. This coupled with our conditional actions (IF, GOTO, LABEL) enable you to move much of your conditional logic into Shoutpoint to cut down on chatter between our server and your server which increases reliabity and speed, and cuts down on the code you have to maintain in handling callbacks requests.

Actions

COLLECT

Record Keypresses from Callers.

A loop can contain one or more COLLECT action. The results will be returned in the callback and identified by the COLLECT action’s name.

The COLLECT object also accepts an actions array (optional). This array accepts PLAY, SAY, and PAUSE actions. These “child actions” will play before a COLLECT and cancel all on the first key press, letting the COLLECT action record the key without waiting.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
finish_on_key The key to press to end the timeout when key presses are less than num_digits. Accepts: off, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. # string No
num_digits The maximum number of key presses to record before leaving the COLLECT action. 1 number No
timeout How long in milliseconds to wait for the next key press. 5000 number No

Example Response

{  
   "actions":[  
      {  
         "name":"rating",
         "type":"COLLECT",
         "actions":[  
            {  
               "type":"SAY",
               "params":{  
                  "text":"Press 1 for yes. Press 2 for no."
               }
            }
         ],
         "params":{  
            "finish_on_key":"#",
            "num_digits":1,
            "timeout":5000
         },
         "comments":"Rating of the user experience."
      }
   ]
}

Example Response // Advanced

{  
   "actions":[  
      {  
         "$nextUrl":"'operator.json'"
      },
      {  
         "type":"LABEL",
         "name":"PROMPT_MENU_CHOICE"
      },
      {  
         "type":"COLLECT",
         "actions":[  
            {  
               "type":"SAY",
               "params":{  
                  "text":"Press1forsales.Press2forservice."
               }
            }
         ],
         "params":{  
            "num_digits":1
         }
      },
      {  
         "type":"IF",
         "condition":"! $keyPresses && $collectAttempt < 3",
         "then":[  
            {  
               "type":"GOTO",
               "params":{  
                  "label":"PROMPT_MENU_CHOICE"
               }
            }
         ]
      },
      {  
         "type":"IF",
         "condition":"$keyPresses=='1'",
         "then":[  
            {  
               "$nextUrl":"'sales.json'"
            }
         ]
      },
      {  
         "type":"IF",
         "condition":"$keyPresses=='2'",
         "then":[  
            {  
               "$nextUrl":"'service.json'"
            }
         ]
      },
      {  
         "type":"REDIRECT",
         "params":{  
            "url":"${nextUrl}"
         }
      }
   ]
}

CONFERENCE

Initiates a conference event.

The first event will be ‘join’ to put the caller into a conference. The other events can then be invoked.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
name A unique name to identify the conference. Using the same name will put callers into the same conference. Accepts: alpha-numeric, underscores, and dashes. string * Yes
event The conference event to trigger for the caller. Accepts: join, leave, mute, unmute, hold, resume. join string No
hold_audio The url of the audio file to play when a participant is on hold. If omitted, our default hold music will play. Supports MP3 and WAV. WAV will often perform better. string No
auto_hold If true, the conference will automatically play hold music if only one call is in the room. false boolean No
join_muted Indicates whether the participant joins the conference muted or not. false boolean No
async If true, this action will not block and the call flow will continue executing actions and/or callback. Be careful as async may cause hard to reason behaviors. false boolean No
max_participants At the moment of joining, if the number of conference participants exceeds this amount, the joiner will be blocked. Participants who attempt to exceed the limit can be handled with an error handler. Infinity** number No
announce_on_join Causes a beep to play to the conference when a participant joins and leaves. Accepts: beep or null. null string No
mute_on_key Which key press will let the caller mute himself. Accepts: #, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, or off to disable this feature. off string No
unmute_on_key Which key press will let the caller unmute himself. Accepts: #, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, or off to disable this feature. off string No
exit_on_key Which key combination will let the caller exit the conference. Accepts: #, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, or off to disable this feature. off string No
hold_on_join If true, participants will enter the Conference on hold until a participant joins with start_on_join. false boolean No
start_on_join If true, the Conference will start and remove everybody from hold. Used with hold_on_join. true boolean No
end_on_exit If true, the Conference will immediately end when this participant leaves. All other participants will resume the call flow. false boolean No
hold_on_exit If true, when this participant leaves the Conference, all other participants will be put on hold. false boolean No

Example Response // Simple

{  
   "actions":[  
      {  
         "type":"CONFERENCE",
         "params":{  
            "name":"my-conference"
         }
      }
   ]
}

Example Response // Advanced

{  
   "actions":[  
      {  
         "type":"CONFERENCE",
         "params":{  
            "name":"my-conference",
            "event":"join",
            "max_participants":10,
            "mute_on_key":"1",
            "unmute_on_key":"3",
            "exit_on_key":"#0"
         },
         "events":{  
            "on_enter":[  
               {  
                  "type":"SAY",
                  "params":{  
                     "text":"You are now joining the conference."
                  }
               },
               {  
                  "type":"WEBHOOK",
                  "params":{  
                     "event_name":"onEnterConference"
                  }
               }
            ],
            "on_enter_error_max_participants":[  
               {  
                  "type":"SAY",
                  "params":{  
                     "text":"I'm sorry. The conference is full."
                  }
               }
            ]
         }
      }
   ]
}

Note: To hear another call’s early media, you must have the CONFERENCE action as the first action. It also cannot have any on_enter event handlers. Conferences can trigger events when a participant joins or a join attempt fails. Attempts can fail, for example, if the max participants limit is reached. Event handlers are a list of actions that execute when specified events are triggered.

Events

Event Description
on_enter_started This handler will run when a Conference is in progress. By default, Conferences are created in progress. hold_on_join will cause a Conference to wait for specified participants before starting.
on_enter_waiting This handler will run when a Conference uses hold_on_join=“true” and no start_on_join=“true” participant has entered yet.
on_enter This is a catch-all handler. These actions will always execute last.
on_enter_error_max_participants This handler will run when a participant attempts to join a Conference that is at its max_participants limit.
on_enter_error_ended This handler will run when a participant attempts to join a Conference that has ended.
on_enter_error This handler will always run on any error condition.
on_enter_alone This handler will run when a caller enters a conference and is the only conference participant.

DETECT

BETA

Detects whether a live person or voicemail system answers the outbound call.

If the callee is a voicemail service, the action will wait to execute the on_voicemail event after the beep.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
trigger_live_in_ms Change the default wait time after the call connects to detect live person or voicemail before playing the live person event by default. 3000 integer No

Detect Events

Event Description Required
on_live_person This even is triggered when a live person answers the call. While within this event, DETECT is still listening and may later determine (hears a beep) that the call was indeed answered by a voicemail system. In that circumstance, the “on_voicemail” event will fire. Best practice dictates providing an initial greeting for the live person, allowing the call to exit the “on_live_person” event in 5-10 seconds, and then continuing on with the regular call flow. Yes
on_voicemail This event is triggered when a voicemail system has answered the phone and is ready to record the message (for example, after a beep). You will likely want to hang up or leave a message with SAY or PLAY. Yes
on_voicemail_early This optional event fires as soon as DETECT recognizes a voicemail system. Use this event when you want to handle a voicemail call as soon as possible. For example, hang up to save minute charges. No

Example Response

{  
   "type":"DETECT",
   "params":{  
      "trigger_live_in_ms":3000
   },
   "events":{  
      "on_live_person":[  
         {  
            "type":"SAY",
            "params":{  
               "text":"Welcome to the call. You will be joined to the conference shortly."
            }
         }
      ],
      "on_voicemail":[  
         {  
            "type":"SAY",
            "params":{  
               "text":"Sorry we missed you. We will try to call you at a later time."
            }
         }
      ]
   }
}

DIAL

Initiates a new, independent phone call (not connected to the current call).

While this action initiates a new phone call during the middle of another live call, it does not connect the two calls together; rather, it dials the specified no and, upon answer, routes the call to the given call flow config, based on the caller_id_no.

DIAL is useful in call flows where you are dropping two or more callers into a conference, but you want to retain control over all legs of the call, like click to call, shark tank, etc.

If you are trying to connect two callers, and you do not need to retain control over the second leg of the call, you can use the TRANSFER action.

NOTE: To initiate a phone call via our REST API, see Make Call.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
no The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as [email protected] string * Yes
caller_id_no The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). This phone number should have been previously provisioned and assigned to CallFlows and configured with a CallFlow Callback. Defaults to the inbound number (api_no in your callback). string * No
detection How to identify a connection. Accepts: preconnect, full, none. none string No
inbound_api The inbound API to route the call to. Currently only uses CallFlows. CallFlows string No
disable_redial_block To prevent unintentional DIAL loops, redialing the same phone number is blocked with a message and hangup. Only set this parameter to true when you are deliberately redialing a number. false boolean No
session_data This object will be included in the CallFlows callback, allowing custom data to be passed on dial. object or string * No

Events

Event Description
on_error If this DIAL action fails for any reason, this event will fire and execute any actions therein. The reason for the error can be found in the Call Logs.

Example Responses

{  
   "actions":[  
      {  
         "type":"DIAL",
         "params":{  
            "no":"+19495551111"
         }
      },
      {  
         "type":"DIAL",
         "params":{  
            "no":"[email protected]",
            "caller_id_no":"+17145552222",
            "detection":"preconnect",
            "inbound_api":"CallFlows"
         },
         "session_data":{  
            "name":"Bob",
            "age":21,
            "isNice":true
         }
      },
      {  
         "type":"DIAL",
         "params":{  
            "no":"+19495551111",
            "caller_id_no":"+17145552222"
         },
         "session_data":"$sessionData"
      },
      {  
         "type":"DIAL",
         "params":{  
            "no":"+19495551111",
            "caller_id_no":"+17145552222"
         },
         "events":{  
            "on_error":[  
               {  
                  "type":"SAY",
                  "params":{  
                     "text":"This call could not be dialed."
                  }
               }
            ]
         }
      }
   ]
}

FOREACH

The FOREACH Action is a convenient way to loop through an array or object without having to worry about counting the number of elements.

The FOREACH Action loops through a provided list of Actions once for each element in the data structure, automatically exiting when the elements are all exhausted. This list of Actions has access to each value, key and index of the current element.

Request

View standard request details HERE

Response

Parameter Description Type Default Req
params.iterator The variable with the assigned array or object, string Yes
params.valueVar The variable to assign the iterator’s next value. string $val No
params.keyVar The variable to assign the next object key or array index. string $key No
params.indexVar The variable to assign the next array index or “loop counter”. string $index No
then The list of actions to run on each element. Action[] Yes

Example Response

{
   "actions":[
      {
         "$myPetsArray":"['Whiskers', 'Spot', 'Bubbles']"
      },
      {
         "type":"FOREACH",
         "params":{
            "iterator":"$myPetsArray"
         },
         "then":[
            {

           "type":"SAY",
               "params":{
                  "text":"The index ${index} has a value of ${val}."
               }
            }
         ]
      },
      {
         "$myPetsObj":"{cat: 'Whiskers', dog: 'Spot', fish: 'Bubbles'}"
      },
      {
         "type":"FOREACH",
         "params":{
            "iterator":"$myPetsObj",
            "valueVar":"$v",
            "keyVar":"$k"
         },
         "then":[
            {
               "type":"SAY",
               "params":{
                  "text":"The key ${k} has a value of ${v}."
               }
            }
         ]
      },
      {
         "$phoneNos":"['+17145551212', '+13105551212', '+19495551212']"
      },
      {
         "type":"FOREACH",
         "params":{
            "iterator":"$phoneNos"
         },
         "then":[
            {
               "type":"DIAL",
               "params":{
                  "no":"${val}"
               }
            }
         ]
      },
   ]
}

GOTO

Jump to a LABEL.

The GOTO action jumps the call flow to the specified LABEL. Warning: The call flow will fail if the specified LABEL does not exist within the same callback response.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
label Accepts: alphanumeric characters, dashes, and underscores. string * Yes

Example Response

{  
   "actions":[  
      {  
         "type":"GOTO",
         "params":{  
            "label":"goto_here"
         }
      }
   ]
}

HANGUP

Ends the call.

This action immediately ends the call and stops all action flow execution.

Request

View standard request details HERE

Response

See Example Body

Example Response

{  
   "actions":[  
      {  
         "type":"HANGUP"
      }
   ]
}

IF

Basic if-then-else conditional. The IF action allows the call flow, based on a true/false evaluation of a condition, to execute or skip a block of actions.

The variables within the scope of the condition are basically the callback Native Constants and User Defined Variables prefixed with a $ symbol (yeah, like PHP). The condition is evaluated as JavaScript, with all of its truthy goodness.

Response

Parameter Description Default Type Required
condition The JS statement to evaluate for truthfulness. string Yes
then The list of actions to execute if the condition is TRUE. array Yes
orElse Optionally, the list of actions to execute if the condition is FALSE. array No

Example Response

{  
   "actions":[  
      {  
         "type":"IF",
         "condition":"$keyPresses == '1' && $sessionData.gender == 'male' || $sessionData.age > 21",
         "then":[  
            {  
               "type":"SAY",
               "params":{  
                  "text":"You pressed 1, dude. Or you are over 21."
               }
            }
         ],
         "orElse":[  
            {  
               "type":"SAY",
               "params":{  
                  "text":"You did not press 1 and are not a male or are not over 21."
               }
            }
         ]
      }
   ]
}

LABEL

Target of GOTO.

The LABEL action sets the entry point for a GOTO action. Invoking a GOTO on a label will immediately jump the call flow to the LABEL.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
name The name of the LABEL used by a GOTO action. Accepts: alphanumeric, dashes and underscores. string Yes

Example Response

{  
   "actions":[  
      {  
         "type":"LABEL",
         "name":"goto_here"
      }
   ]
}

PAUSE

Pauses the call.

Pauses the call for the specified number of seconds, then resumes with the next Action.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
seconds The number of seconds to pause. 5 number No

Example Response

{  
   "actions":[  
      {  
         "type":"PAUSE",
         "params":{  
            "seconds":10
         }
      }
   ]
}

PLAY

Plays an audio file or DTMF.

Audio files supported are MP3 and WAV. WAV will often perform better.

DTMF will play an out-of-band tone.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
url The url of the audio file. string * Yes*
stop_on_key Should a key press stop the playback (for URL only)? false boolean No
dtmf The DTMF tones to play. Accepts: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. Use a dash - to extend the delay between DTMF tones. Example: 12-3--4---5. string * Yes*
dtmf_delay The delay between DTMF tones in milliseconds (for DTMF only). 250 number No
dtmf_dash_delay The delay represented by each dash - in milliseconds (for DTMF only). 250 number No
repeat How many times to repeat the audio or DTMF. 1 number No
parse_vars true to parse variables in the URL/DTMF or false to leave as-is. true boolean No

Example Response // Audio

{  
   "type":"PLAY",
   "params":{  
      "url":"https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3",
      "repeat":1,
      "stop_on_key":true,
      "parse_vars":false
   }
}

Example Response // DTMF

{  
   "type":"PLAY",
   "params":{  
      "dtmf":"1 2 3 - 4 -- 5 --- 6"
   }
}

QUEUE

Controls Call Queues.

Place or remove callers from a specific queue and handle queue events.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
name A unique name to identify the queue. Using the same name will put callers into the same queue. Accepts: alpha-numeric, underscores, and dashes. string * Yes
event Accepts: offer, poll, poll_connect, remove.

offer puts this call into a queue.
poll releases the next queued call from a queue (and has a limited use case as an Action).
poll_connect takes the next call from the queue and bridges it to this call.
remove takes this call (regardless of position) from the queue.
offer string No
hold_audio The url of the audio file to play when a call is in the queue. If true, our default hold music will play. If false, no hold music will play. Supports MP3 and WAV. WAV will often perform better. true string/boolean No
async If true, this action will not block and the call flow will continue executing actions and/or callbacks. Be careful as async may cause hard to reason behaviors. Only offer can be asynchronous. false boolean No
max_calls At the moment of offering, if the number of queued calls exceeds this amount, the offer will error. Calls that attempt to exceed the limit can be handled with an error handler. infinity* number No

Example Response // Simple

{  
   "actions":[  
      {  
         "type":"QUEUE",
         "params":{  
            "name":"high-priority"
         }
      }
   ]
}

NOTE: When a call is polled/removed from a blocking queue, it continues down the call flow. If using poll_connect, you will likely want to block when the polled call exits the queue. Use a PAUSE or COLLECT action.

Queues can trigger events when a offer attempt succeeds or fails. Attempts can fail, for example, if the max calls limit is reached. Event handlers are a list of actions that execute when specified events are triggered.

Queue Events

Event Description
on_enter This handler will run when an offer is accepted.
on_enter_error_max_calls This handler will run when a queue is at its max_calls limit.
on_enter_error This handler will always run on any error condition, including a poll_connect failure.

Example Response // Advance

{  
   "actions":[  
      {  
         "type":"QUEUE",
         "params":{  
            "name":"low-priority",
            "event":"offer",
            "max_calls":10
         },
         "events":{  
            "on_enter":[  
               {  
                  "type":"SAY",
                  "params":{  
                     "text":"You are now entering the queue."
                  }
               }
            ],
            "on_enter_error_max_calls":[  
               {  
                  "type":"SAY",
                  "params":{  
                     "text":"I'm sorry. The queue is full."
                  }
               }
            ]
         }
      }
   ]
}

RECORD

Control call recording.

This action allows the developer to start, stop, pause and resume recordings.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
group A name that is queryable in the recordings lookup resource. api_no string No
action The recording action to perform. Accepts: start, stop, pause, resume. start string No

Example Response

{  
   "actions":[  
      {  
         "type":"RECORD",
         "params":{  
            "group":"support_technical",
            "action":"start"
         }
      }
   ]
}

REDIRECT

Changes the callback URL, etc.

The REDIRECT action changes the url, method, headers and/or content_type of all subsequent callbacks.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
url The new url to send all subsequent callbacks to. This parameter supports relative URLs. The benefit of relative URLs is that actions with REDIRECTs may be assigned to many domains or subdirectories without changing any code. string * Yes
method The new method to send all subsequent callbacks as. Accepts: POST, PUT, GET. GET string * No
headers The new headers to send with all subsequent callbacks. Accepts an associative array of header names and values. object No
content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. application/json string * No

Example Response

{  
   "actions":[  
      {  
         "type":"REDIRECT",
         "params":{  
            "url":"https://your-domain.com/path/to/here",
            "method":"GET"
         }
      }
   ]
}

Example Response // Relative URL


"https://domain.com/path/to/actions/file.json"

{  
   "actions":[  
      {  
         "type":"REDIRECT",
         "params":{  
            "url":"other_file.json"
         }
      }
   ]
}

"Resolves to https://domain.com/path/to/actions/other_file.json"

Example Response // Relative URL


"https://domain.com/path/to/actions/file.json"

{  
   "actions":[  
      {  
         "type":"REDIRECT",
         "params":{  
            "url":"../../other_file.json"
         }
      }
   ]
}

"Resolves to https://domain.com/path/other_file.json"

REJECT

Does not answer the call.

This action refuses to answer the call. Depending on the reason given, a busy-signal or not-in-service message will be played.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
reason Accepts: busy and disconnected. busy string No

Example Response

{  
   "actions":[  
      {  
         "type":"REJECT",
         "params":{  
            "reason":"busy"
         }
      }
   ]
}

SAY

Convert text to speech (TTS).

The SAY action converts text to speech that is read to the caller.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
text The text to convert. string * Yes
stop_on_key Determines whether a key press stops the playback. false boolean No
repeat The number of times to play the speech. 1 number No
parse_vars true to parse variables in the “text” string. false leaves untouched. true boolean No
voice Accepts: Kate and Kevin (Shoutpoint native voices), Watson (requires an IBM Watson Account) Kate string No
language Accepts: english (Kate and Kevin) AND englishUS, englishGB, french, german, italian, japanese, portugese, spanish (IBM Watson) english string No
gender Accepts: female, male female string No

Example Response

{  
   "actions":[  
      {  
         "type":"SAY",
         "params":{  
            "text":"Hello, world.",
            "repeat":2,
            "parse_vars":false,
            "voice":"Kate",
            "language":"english",
            "gender":"female"
         }
      }
   ]
}

SESSIONDATA

Sets a call’s session data.

Sets a call’s session_data property.

To learn more about session data, click here.

Request

View standard request details HERE

Response

Name Description Type
session_data The session data value can be any valid JSON object. object

Example Response

{  
   "actions":[  
      {  
         "type":"SESSIONDATA",
         "session_data":{  
            "name":"Bob",
            "age":21,
            "isNice":true
         }
      }
   ]
}

SMS

Sends an SMS message.

This action sends an SMS message.

Response

Parameter Description Default Type Required
message The text message to send. string * Yes
no The phone number to send the message to. Defaults to caller’s number. caller_no string * No
caller_id_no The phone number the message is sent from. Defaults to the current inbound number. api_no string * No

Example Response

{  
   "actions":[  
      {  
         "type":"SMS",
         "params":{  
            "no":"+19495551111",
            "caller_id_no":"+17145552222",
            "message":"Hello, world!"
         }
      }
   ]
}

STOP

Stops Running Actions.

This action stops other actions that are currently running on a call, like playing audio.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
actions A comma-separated list of actions. Accepts: AUDIO. AUDIO string No

Example Response

{  
   "actions":[  
      {  
         "type":"STOP",
         "params":{  
            "actions":"AUDIO"
         }
      }
   ]
}

TRANSFER

Transfers the call.

This action transfers the caller from the current api_no to another phone number or SIP endpoint.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
no The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as [email protected] string * Yes
caller_id_no The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). Defaults to the number of the caller that dialed your inbound number (caller_ no in your callbacks) caller_no string * No
event Accepts start or stop. The start event will connect two calls. The stop event will disconnect the transfer, hanging up on the other call. start string No
async If false, the default, the current call will block for the duration of the transfer call. If true, the transfer will be initiated, but the current call will continue with its call flow. false boolean No

Example Response // Phone Number

{  
   "actions":[  
      {  
         "type":"TRANSFER",
         "params":{  
            "no":"+19495551111",
            "caller_id_no":"+17145552222"
         }
      }
   ]
}

Example Response // SIP Address

{  
   "actions":[  
      {  
         "type":"TRANSFER",
         "params":{  
            "no":"[email protected]",
            "caller_id_no":"+17145552222"
         }
      }
   ]
}

Example Response // Async Transfer

{  
   "actions":[  
        {
            "type": "TRANSFER",
            "params": {
                "no": "+17145551212",
                "async": true
            }
        },
        {
            "type": "COLLECT",
            "params": {
                "num_digits": 1,
                "timeout": 3600000
            },
            "actions": [{
                "type": "SAY",
                "params": {
                    "text": "Press any key to end the call."
                }
            }]
        },
        {
            "type": "TRANSFER",
            "params": {
                "event": "stop"
            }
        }
   ]
}

WEBHOOK

HTTP Request.

This action allows HTTP requests from anywhere in the call flow. For example, add WEBHOOK to CONFERENCE or QUEUE event handlers to alert your service when a call enters a conference or queue.

You can use WEBHOOK to alert your service when a call exits a conference or queue by placing a WEBHOOK immediately after blocking CONFERENCE or QUEUE actions.

The default value “Inherited” means that the value will equal that of the last Call Flow Callback Request. The request timeout is 30 seconds.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
event_name The name of the webhook event. This can be anything you like. Examples: onEnterConference, onLeaveQueue, onEnterQueueError. string Yes
webhook_data This data will simply be returned in the webhook request. {} object or string * No
url The endpoint the webhook will call. Inherited string No
method The method of the request. Accepts: GET, POST, PUT. Inherited string No
content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Inherited string No
headers The headers to include in the request. Inherited key/value No
await_response If true, the request will wait for a JSON response and make it available via the $webhookData variable. This forces the WEBHOOK to be non-asynchronous (blocking). Inherited boolean No

Events

Event Description
on_error This handler will run when a WEBHOOK response status is non-2xx. Forces the WEBHOOK to be non-asynchronous (blocking).

Example Response // Simple

{  
   "actions":[  
      {  
         "type":"WEBHOOK",
         "params":{  
            "event_name":"onEnterConference"
         }
      }
   ]
}

Example Response // Advanced // Object

{  
   "actions":[  
      {  
         "type":"WEBHOOK",
         "params":{  
            "event_name":"onEnterConference",
            "webhook_data":{  
               "conferenceName":"my-conf"
            },
            "url":"https://mydomain.com/app/webhook",
            "method":"POST",
            "content_type":"application/json",
            "await_response": true
         },
         "events": {
            "on_error": [
                    {
                        "type": "SAY",
                        "params": {
                            "text": "A webhook error occurred."
                        }
                    },
                    { "$webhookData": "{ foo: 'I got no foo' }" }
            ]
         }
      }
   ]
}

Example Response // Simple // String

{  
   "actions":[  
      {  
         "type": "WEBHOOK",
         "params": {  
            "event_name": "onEnterConference",
            "webhook_data": "$dataMap.webhookData"
         }
      }
   ]
}

Example Response // Advanced // String

{  
   "actions":[  
      {  
         "type":"WEBHOOK",
         "params":{  
            "event_name":"onEnterConference",
            "webhook_data": "$dataMap.webhookData",
            "url":"https://mydomain.com/app/webhook",
            "method":"POST",
            "content_type":"application/json"
         }
      }
   ]
}

Methods

Account

View Account Detail

Returns account owner’s information.

GET /Account

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Response

Property Description Type
id Account ID string
email Account Owner’s Email string
firstname Acount Owner’s First Name string
lastname Account Owner’s Last Name string
username Account Owner’s Username (will be email) string
status Returns: active or inactive string
max_apps The maximum number of Apps an account can create (includes deleted Apps) number
max_subaccounts The maximum number of Sub Accounts per App (includes deleted Sub Accounts) number

Example Response:

{
  "id": "8c86b1f5-abcd-1234-efgh-h249d0e298",
  "email": "[email protected]",
  "firstname": "John",
  "lastname": "Doe",
  "username": "[email protected]",
  "status": "active",
  "max_apps": 15,
  "max_subaccounts_per_app": 20

}

Response Codes

Status Description
200 Success returns account details
4xx & 5xx General Error Codes

Alerts

Create Alert

Creates an email alert specifically for your account based upon balance thresholds. Used to warn recipient when specified account balance is getting low.

POST /Account/Alerts

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
firstname The first name of the alert recipient. string Yes
lastname The last name of the alert recipient. string Yes
email The email address to send the alert to. string Yes
phone_no The phone number of the alert recipient. As of now, not used. string No
account_balance The configuration for the alerts. The properties minutes_before_zero and/or thresholds are required. object Yes
account_balance.minutes_before_zero Trigger an alert the specified number of minutes before the account balance is estimated to hit $00.00. number No
account_balance.thresholds One to three dollar amounts of the account balance that will trigger an alert, separated by commas. array number No

Example Request

{  
   "firstname":"John",
   "lastname":"Doe",
   "email":"[email protected]",
   "phone_no":"714-555-1212",
   "account_balance":{  
      "minutes_before_zero":30,
      "thresholds":[  
         10,
         100,
         1000
      ]
   }
}

Response

No Response Body

Response Codes

Status Description
201 Success creates new alert
4xx & 5xx General Error Codes

List Alerts

Returns all alerts created for a specific account.

GET  /Account/Alerts

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Response

Property Description Type
alerts An array of Alerts array
alerts[].id Alert ID string
alerts[].firstname First Name of alert recipient string
alerts[].lastname Last Name of alert recipient string
alerts[].email Email of alert recipient (where alert will be sent) string
alerts[].phone_no Phone number of alert recipient string
alerts[].account_balance object
alerts[].account_balance.minutes_before_zero Send an alert this many minutes before the account balance is estimated to reach zero. number
alerts[].account_balance.thresholds Send an alert when each of these thresholds are crossed. number[]

Example Response

{  
   "alerts":[  
      {  
         "id":8411,
         "firstname":"John",
         "lastname":"Doe",
         "email":"[email protected]",
         "phone_no":"(949) 555-1212",
         "account_balance":{  
            "minutes_before_zero":30,
            "thresholds":[  
               10,
               100,
               1000
            ]
         }
      }
   ]
}

Response Codes

Status Description
200 Success returns an array of alerts.
4xx & 5xx General Error Codes

Delete Alert

Deletes an alert by ID. The ID is the only required parameter.

DELETE /Account/Alerts/{id}

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Response

No Response Body

Response Codes

Status Description
204 Success returns no content.
4xx & 5xx General Error Codes

Application Sub Accounts

Create Sub Accounts

Creates a new Sub Account under the appropriate application based upon the API Key used to authenticate.

POST /SubAccounts

Authentication Type

API Key (Application-level)

Request

Parameter Description Type
name The name of the Sub Account. string

Example Request

{
    "name": "My First Sub Account"
}

Response

Parameter Description Type
id The ID of the Sub Account integer
name The name string
sip_domains The available SIP URI endpoints for this Sub Account object
sip_domains.callflows The unique SIP URI for CallFlows string

Example Response

{
  "id": "0",
  "name": "My Sub Account",
  "sip_domains": {
     "callflows": "1234-56789.accounts.sip.shoutpoint.com"
  }

}

Response Codes

Status Description
201 Success returns a response
4xx & 5xx Sub Account Error Codes

List Sub Accounts

Returns a list of all Sub Accounts under your application.

GET /SubAccounts

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
app_id The ID of the App string
subaccounts[] List of Sub Accounts array
subaccounts[].id The name of the Sub Account. string
subaccounts[].name The name of the Sub Account. string

Example Response

{  
   "app_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "subaccounts":[  
      {  
         "id":0,
         "name":"My First Sub Account"
      }
   ],
   "pagination":{  
      "current_page":0,
      "total_pages":1,
      "total_items":1,
      "items_per_page":10
   }
}

Response Codes

Status Description
200 Success returns a list of Sub Accounts
4xx & 5xx Sub Account Error Codes

View Sub Account Detail

Returns the Sub Account detail for any individual Sub Account based upon the Sub Account ID.

GET /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
id The ID of the Sub Account integer
name The name of the Sub Account. string
sip_domains The available SIP URI endpoints for this Sub Account object
sip_domains.callflows The unique SIP URI for CallFlows string

Example Response

{
   "id": 0, 
   "name": "My First Sub Account",
   "sip_domains": {
     "callflows": "1234-56789.accounts.sip.shoutpoint.com"}
}

Response Codes

Status Description
200 Success returns a Sub Account detail
4xx & 5xx Sub Account Error Codes

Update Sub Account

Not yet available, but coming soon.

Modifies the Sub Account detail for any individual Sub Account based upon the Sub Account id.

PUT /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type
name The name of the Sub Account. string

Example Request

{
   "name": "My First Sub Account" 
}

Response

Parameter Description Type
id The ID of the Sub Account string
name The name of the Sub Account array

Example Response

{
   "id": 1234, 
   "name": "My First Sub Account" 
}

Response Codes

Status Description
201 Success returns name and ID of Sub Account which was updated.
4xx & 5xx Sub Account Error Codes

Delete Sub Account

Deletes the specific Sub Account based on the Sub Account ID.

DELETE /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

No Response Body

Response Codes

Status Description
204 Success returns no response
4xx & 5xx Sub Account Error Codes

Billings

View Balance

Returns the current account balance of the account. Services will stop when the balance equals $00.00. Use the Portal or Make Payment to add funds.

GET /Account/Billings/Balance

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Response

Property Description Type
balance Current account balance in USD. number

Example Response

{
  "balance": 100.00
}

Response Codes

Status Description
200 A successful request returns the balance.
4xx & 5xx General Error Codes

Caller IDs

Create Caller ID

Creates a Caller ID. Caller IDs enable you make outbound calls that appear to be from a phone number that you assert. Caller IDs must be in E.164 format. Example: +17145551212.

Note: To place a call via a CallerId, it must be verified first. See POST /CallerIDs/{callerId}/Verify.

POST /CallerIDs/{callerId}

Authentication Type

API Key (Application-level)

Request

{callerId} - e164 formatted phone number (+17145551212).

Parameter Description Type Required
description The description of the callerId. string No

Example Request

{  
  "description":"Desk Phone"
}

Response

Parameter Description Type
no The Caller ID in e164 format. string
formatted The Caller ID in human-friendly format. string
capabilities[] Currently, will only/always contain voice_outbound for Caller IDs. string[]
description The user-defined description for the Caller ID. string
status The status: verified, unverified, blocked. string
usage The count of all-time calls from this Caller ID. number

Example Response

{
  "no": "+17145551212",
  "formatted": "(714) 555-1212",
  "capabilities": [
    "voice_outbound"
  ],
  "description": "Desk phone at work.",
  "status": "unverified",
  "usage": 0
}

Response Codes

Status Description
200 Returns Caller ID Object
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

List Caller IDs

Returns a list of Caller IDs.

GET /CallerIDs

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
caller_ids[] An array of currently active CallerID details. object
caller_ids[].no The Caller ID in e164 format. string
caller_ids[].formatted The Caller ID in human-friendly format. string
caller_ids[].capabilities[] Will only/always contain voice_outbound for Caller IDs. array
caller_ids[].description The user-defined description for the Caller ID. string
caller_ids[].status The status: verified, unverified, blocked. string
caller_ids[].usage The count of all-time calls from this Caller ID. number

Example Response

{
  "caller_ids": [
    {
      "no": "+17145551212",
      "formatted": "(714) 555-1212",
      "capabilities": [
        "voice_outbound"
      ],
      "description": "Desk phone at work.",
      "status": "unverified",
      "usage": 0
    }
  ]
}

Response Codes

Status Description
200 Returns a list of callerIDs.
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

View Caller ID

Returns the CallerID configuration of a specific phone number. Phone number must be in E.164 format. (example: +17145551212)

GET /CallerIDs/{callerId}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
no The Caller ID in e164 format. string
formatted The Caller ID in human-friendly format. string
capabilities[] Currently, will only/always contain voice_outbound for Caller IDs. string[]
description The user-defined description for the Caller ID. string
status The status: verified, unverified, blocked. string
usage The count of all-time calls from this Caller ID. number

Example Response

{
  "no": "+17145551212",
  "formatted": "(714) 555-1212",
  "capabilities": [
    "voice_outbound"
  ],
  "description": "Desk phone at work.",
  "status": "unverified",
  "usage": 0
}

Response Codes

Status Description
200 Returns Caller ID Object
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

Update Caller ID

Updates the CallerID configuration of a specific phone number. Phone number must be in E.164 format. (example: +17145551212)

PUT /CallerIDs/{callerId}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type
description The user-defined description for the Caller ID. string

Example Request

{
  "description": "Desk phone at work."
}

Response

Parameter Description Type
no The Caller ID in e164 format. string
formatted The Caller ID in human-friendly format. string
capabilities[] Currently, will only/always contain voice_outbound for Caller IDs. string[]
description The user-defined description for the Caller ID. string
status The status: verified, unverified, blocked. string
usage The count of all-time calls from this Caller ID. number

Example Response

{
  "no": "+17145551212",
  "formatted": "(714) 555-1212",
  "capabilities": [
    "voice_outbound"
  ],
  "description": "Desk phone at work.",
  "status": "unverified",
  "usage": 0
}

Response Codes

Status Description
200 Returns Caller ID Object
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

Delete Caller ID

Deletes the CallerID configuration of a specific phone number. Phone number must be in E.164 format. (example: +17145551212)

DELETE /CallerIDs/{callerId}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

No Response Body

Response Codes

Status Description
204 No response if successful
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

Verify Caller ID

This request will trigger a call to the given phone number. After the message, the PIN in the response must be entered to allow the Caller ID to be used in outbound dialing.

POST /CallerIDs/{callerId}/Verify

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
id The reference ID of the verify request. Not used in the API. number
verify_pin The digits to enter during the verification phone call. string

Example Response

{
  "id": 12345,
  "verify_pin": "9876"
}

Response Codes

Status Description
200 Verification information, like the PIN code.
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

Call Flows (Callback Configuration)

Create Call Flow Callback

Creates the settings for Inbound Phone Numbers or Caller IDs. CallFlows parameters include the callback.url where Shoutpoint will send Callback Requests to retrieve instructions for what you want us to do on the call (using our Call Flow Actions).

NOTE: If Inbound Phone Numbers have been assigned to /ParkingLot, all CallFlows settings will be ignored. Inbound Phone Numbers must to be assigned to PhoneNumber/CallFlows to be controlled.

POST /CallFlows/Callbacks

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
no The phone number in E.164 format (example: +17145551212) or SIP_DOMAIN (example: 1234-56789.accounts.sip.shoutpoint.com) to configure. string Yes
callback An object that describes the callback parameters. object Yes
callback.url The endpoint URL where the request will be sent. string Yes
callback.method The request method. Accepts: POST, GET. Default: POST. string No
callback.content_type The format of the payload posted to the endpoint. Options: application/json, application/xml and application/x-www-form-urlencoded. Default: application/json. string No
callback.headers An associative array of header names and values to include in every request. object No
callback.timeout In seconds, the time for the callback request to wait for a response before timing out. Allowed range: 1 - 15. Default: 5. number No
callback.answer_on_ring The number of allowed rings before the call is answered. Allowed range: 1 - 10. Default: 1. integer No
callback_failover If the callback request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. object No
callback_sms The endpoint for inbound SMS callbacks to request. If not set, the default callback object is used. Contains the same properties as the callback object. object No
callback_sms_failover If the callback_sms request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. object No
is_template If true, Template Mapping. will be found and replaced. Default: true. boolean No
log_callbacks_until The date/time the callbacks for calls will stopped being logged. This date/time cannot be further out than 24 hours from “now”. Accepts ISO Date strings. Default: current time. string No
custom_data Any data you want included in every request. For example, a private key to verify requests. object No

Example Request // Phone Number

[  
   {  
      "no":"+17145551213",
      "callback":{    
         "method":"POST",
         "url":"https://myserver.com/ivr_app/callback-handler",
         "content_type":"application/json",
         "headers":{  
            "X-Custom-Name":"custom header value"
         }
      },
      "is_template":true,
      "log_callbacks_until": "2017-02-07T18:47:31.886Z",
      "custom_data":{  
         "foo":"bar"
      }
   }
]

Example Request // SIP Domain

[  
   {  
      "no":"1234-56789.accounts.sip.shoutpoint.com",
      "callback":{    
         "method":"POST",
         "url":"https://myserver.com/ivr_app/callback-handler",
         "content_type":"application/json",
         "headers":{  
            "X-Custom-Name":"custom header value"
         }
      },
      "is_template":true,
      "log_callbacks_until": "2017-02-07T18:47:31.886Z",
      "custom_data":{  
         "foo":"bar"
      }
   }
]

Example Request // Minimal Callback Config

[  
   {  
      "no": {
         "value": "+17145551213",
         "type": "US"
      },
      "callback": {    
         "method": "POST",
         "url": "https://myserver.com/ivr_app/callback-handler",
         "content_type": "application/json"
      }
   }
]

Example // Callback Config POST with SMS and Failover Endpoints

[  
   {  
      "no": {
         "value": "+17145551213",
         "type": "US"
      },
      "callback": {    
         "method": "POST",
         "url": "https://myserver.com/ivr_app/callback-handler",
         "content_type": "application/json",
         "headers": {  
            "X-Custom-Name": "custom header value"
         }
      },
      "callback_failover": {    
         "method": "GET",
         "url": "https://s3.amazonaws.com/com.mydomain.actions/failover_actions.json",
         "content_type": "application/json"
      },
      "callback_sms": {    
         "method": "POST",
         "url": "https://myserver.com/ivr_app/callback-sms-handler",
         "content_type": "application/json"
      },
      "callback_sms_failover": {    
         "method": "POST",
         "url": "https://myserver.com/ivr_app/callback-sms-handler-failover",
         "content_type": "application/json"
      },
      "is_template": true,
      "custom_data": {  
         "foo": "bar"
      }
   }
]

Example Template Mapping

{  
   "actions":[  
      {  
         "type":"SAY",
         "params":{  
            "text":"Hello, {{session_data.firstName|guest}}. Welcome to our conference.",
            "loop":1
         }
      },
      {  
         "type":"CONFERENCE",
         "params":{  
            "name":"{{session_data.conferenceName}}"
         }
      },
      {  
         "type":"SAY",
         "params":{  
            "text":"You have left the conference. This call lasted {{duration}} seconds."
         }
      }
   ]
}

Template Mapping

It is possible to automatically insert callback data into your responses with Template Mapping. If is_template is set to true in your configuration, then Template Mapping will be replaced with callback data in your response.

Template Mappings look like {{property}} and {{property|default}}, where property is the callback data property name (flattened) and default is an optional default value to use if no property name match is found.

Response

No Response Body

Response Codes

Status Description
201 List of updated configs.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

List Callback Configurations

Returns current callback configurations.

GET /CallFlows/Callbacks

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
no JSON object with value and type parameters object
no.value The phone number in E.164 format (example: +17145551212) or SIP_DOMAIN (example: 1234-56789.accounts.sip.shoutpoint.com). string
no.type The country code of the phone number (ISO Alpha-2 Code) or SIP_DOMAIN. string
callback An object that describes the callback parameters. object
callback.url The endpoint where the request will be sent. string
callback.method The request method. Returns: POST or GET. string
callback.content_type The format of the payload posted to the endpoint. Options: application/json, application/xml and application/x-www-form-urlencoded. Default: application/json. string
callback.headers An associative array of header names and values to include in every request. object
is_template If true, Template Mapping. will be found and replaced. Default: false. boolean
custom_data Any data you want included in every request. For example, a private key to verify requests. string

Example Response

[  
   {  
      "no":"+17145551212",
      "callback":{  
         "method":"POST",
         "url":"https://myserver.com/ivr_app/callback-handler",
         "content_type":"application/json",
         "headers":{  
            "X-Custom-Name":"custom header value"
         }
      },
      "answer_on_ring":1,
      "last_set_on":"2016-08-08T15:23:01.968Z",
      "custom_data":null,
      "is_template":false,
      "google_analytics":{  
         "tracking_id":"X-12345678-9",
         "source":"CallFlows"
      }
   }
]

Response Codes

Status Description
200 Successful request.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

View Callback Configuration

Returns the callback configuration of a specific phone number. Phone number must be in E.164 format. (example: 17145551212)

GET /CallFlows/Callbacks/{phone_number}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
no JSON object with value and type parameters object
no.value The phone number in E.164 format (example: +17145551212) or SIP_DOMAIN (example: 1234-56789.accounts.sip.shoutpoint.com). string
no.type The country code of the phone number (ISO Alpha-2 Code) or SIP_DOMAIN. string
callback An object that describes the callback parameters. object
callback.url The endpoint where the request will be sent. string
callback.method The request method. Returns: POST or GET. string
callback.content_type The format of the payload posted to the endpoint. Options: application/json, application/xml and application/x-www-form-urlencoded. Default: application/json. string
callback.headers An associative array of header names and values to include in every request. object
is_template If true, Template Mapping. will be found and replaced. Default: false. boolean
custom_data Any data you want included in every request. For example, a private key to verify requests. string

Example Response

{  
   "no":"+17145551212",
   "callback":{  
      "method":"POST",
      "url":"https://myserver.com/ivr_app/callback-handler",
      "content_type":"application/json",
      "headers":{  
         "X-Custom-Name":"custom header value"
      }
   },
   "answer_on_ring":1,
   "last_set_on":"2016-08-08T15:23:01.968Z",
   "custom_data":null,
   "is_template":false,
   "google_analytics":{  
      "tracking_id":"X-12345678-9",
      "source":"CallFlows"
   }
}

Response Codes

Status Description
200 Successful request.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

Delete Callback Configurations

Deletes the callback configuration settings of the specified phone numbers. Phone number must be in E.164 format. (example: 17145551212)

DELETE /CallFlows/Callbacks

Authentication Type

API Key (Application-level)

Request

Parameter Description Type
no The phone number to delete. Accepts: E.164 format. (example: +17145551212) string

Example Request

[
    {
        "no": "+17145551212"
    }
]

Response

Parameter Description Type
no JSON object with value and type parameters object
no.value The phone number in E.164 format (example: +17145551212) or SIP_DOMAIN (example: 1234-56789.accounts.sip.shoutpoint.com). string
no.type The country code of the phone number (ISO Alpha-2 Code) or SIP_DOMAIN. string
callback An object that describes the callback parameters. object
callback.url The endpoint where the request will be sent. string
callback.method The request method. Returns: POST or GET. string
callback.content_type The format of the payload posted to the endpoint. Options: application/json, application/xml and application/x-www-form-urlencoded. Default: application/json. string
callback.headers An associative array of header names and values to include in every request. object
is_template If true, Template Mapping. will be found and replaced. Default: false. boolean
custom_data Any data you want included in every request. For example, a private key to verify requests. string

Example Response

{  
   "no":"+17145551212",
   "callback":{  
      "method":"POST",
      "url":"https://myserver.com/ivr_app/callback-handler",
      "content_type":"application/json",
      "headers":{  
         "X-Custom-Name":"custom header value"
      }
   },
   "answer_on_ring":1,
   "last_set_on":"2016-08-08T15:23:01.968Z",
   "custom_data":null,
   "is_template":false,
   "google_analytics":{  
      "tracking_id":"X-12345678-9",
      "source":"CallFlows"
   }
}

Response Codes

Status Description
200 Success returns the phone numbers of the configurations removed.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

Calls

Make Call

Creates a call to the specified phone number. On connection, the call is put in the specified inbound_api and the callback config for the specified caller_id_no is executed.

POST /Dials/Connect

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call The call object to connect. string Yes
call.no The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as [email protected] string Yes
call.caller_id_no The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). This phone number should have been previously provisioned and assigned to CallFlows and configured with a CallFlow Callback. string Yes
session_data This object will be included in the CallFlows callback, allowing custom data to be passed on dial. object No
inbound_api Defaults to CallFlows. string No
debug_mode If true, forces the call to skip the Configuration cache. Defaults to false. boolean No

Example Request

{  
   "call":{  
      "no":"+17145551212",
      "caller_id_no":"+19495551212"
   },
   "session_data":{  
      "name":"Bob",
      "age":21,
      "isNice":true
   },
   "inbound_api":"CallFlows",
   "debug_mode":true
}

Response

Parameter Description Type
call The call object to connect. string
call.id The ID of the call. string
call.no The phone number dialed. string
call.caller_id_no The from phone number appearing as the caller ID. string
inbound_api The inbound CallFlow type the call.caller_id_no is assigned to. string

Example Response

{  
   "call":{  
      "id":"[email protected]",
      "no":"+17145551212",
      "caller_id_no":"+19495551212"
   },
   "inbound_api":"CallFlows",
   "debug_mode":false
}

Response Codes

Status Description
201 Returns a Call object on success.
4xx & 5xx General Error Codes

List Live Calls

Returns a list of all live calls.

GET /LiveCalls/

Authentication Type

API Key (Application-level)

Request Query

Name Description Type Required
sort_by Sort the call list by connected_time or id. Defaults to connected_time. string No
sort_order The order of call list uses the sort_by field. Accepts:asc, desc. Defaults to asc. string No
filter_on_nos A comma-separated list of phone numbers to filter on. string No
filter_on_call_id_nos A comma-separated list of provisioned phone numbers to filter on string No
filter_on_apis A comma-separated list of APIs to filter on. Accepts: CallFlows string No
include_subaccounts Should the results include the application’s Sub Account calls. Defaults to true. boolean No
max_results The maximum number of calls to return. Default is unlimited. number No
min_connected_time Return calls with connected_time greater than or equal to this value. number No
max_connected_time Returns calls with connected_time less than or equal to this value. number No

Response

Parameter Description Type
calls An array of calls. array
calls.id The ID of the call. string
calls.no The phone number of the caller. string
calls.caller_id_no The from phone number. Basically, not the caller’s number. string
calls.status The status of the call: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. string
calls.date The date and time the call was connected (ISO 8601). string
calls.session_data The session_data set in the /Dials/Connect request and/or the DIALS and SESSIONDATA actions. object
calls.connected_time The call’s duration in milliseconds. long
calls.error null, unless an error occurs. This is an internal diagnostic error and may not be useful to the API developer. string
longest_call The longest call duration retrieved. string
shortest_call The shortest call duration retrieved. string
total_calls The total number of calls retrieved. string

Example Response

{  
   "calls":[  
      {  
         "id":"[email protected]",
         "no":"+17145551212",
         "caller_id_no":"+19495551212",
         "connected_time":12000,
         "status":"live-in-progress",
         "date":"2016-10-10T22:02:54.809Z",
         "session_data":null,
         "app_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
         "subaccount_id":0
      }
   ],
   "longest_call":{  
      "id":"[email protected]",
      "connected_time":12000
   },
   "shortest_call":{  
      "id":"[email protected]",
      "connected_time":12000
   },
   "total_calls":100
}

Response Codes

Status Description
200 Returns an array of Call objects.
4xx & 5xx General Error Codes

View Call Detail

Returns the details of a call by ID.

The details of a call are available to this method for five minutes after the call ends. After that, this method pulls the detail from our logs. There is a chance of this method returning a 404 should the logs take longer than five minutes to update.

GET /LiveCalls/{call_id}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
id The ID of the call. string
no The phone number of the caller. string
caller_id_no The from phone number. Basically, not the caller’s number. string
status The status of the call: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. string
date The date and time the call was connected (ISO 8601). string
session_data The session_data set in the /Dials/Connect request object
connected_time The call’s duration in milliseconds. long
error NULL, unless an error occurs. This is an internal diagnostic error and may not be useful to the API developer. string

Example Response

{  
   "id":"[email protected]",
   "no":"+17145551212",
   "caller_id_no":"+15625551212",
   "connected_time":0,
   "status":"completed",
   "date":"2016-09-07T19:59:08.901Z",
   "session_data":{  
      "name":"Bob",
      "age":21,
      "isNice":true
   },
   "error":null
}

Response Codes

Status Description
200 Returns a Call object.
4xx & 5xx General Error Codes

End Call

Deletes the specified call by ID.

In order to place a message before ending the call, see hangup.

DELETE /LiveCalls/{call_id}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

No Response Body

Response Codes

Status Description
204 The content is empty on success.
4xx & 5xx General Error Codes

Hang Up

Creates a request to end the call by ID.

Includes the option of leaving an exit message.

POST /LiveCalls/{call_id}/Actions/HangUp

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
message The message to play before ending the call. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array Yes

Example Request

{  
   "message":[  
      "Let me play you a song before you go.",
      "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3"
   ]
}

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Collect Digits

Creates a collect key press event in the specified call by ID.

An optional message can be played.

POST /LiveCalls/{call_id}/Actions/Collect

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
message The message to play before collection. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array No
callback The callback object. object Yes
callback.url The url the key presses will be sent to. string Yes
callback.method The method of the request. Accepts: POST, GET, PUT, DELETE. Defaults to POST. string No
num_digits The maximum numbers of digits to accept. Defaults to 1. integer No
finish_on_key The key that ends key press collection. Accepts: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. Defaults to #. string No

Example Request

{  
   "message":"https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3",
   "callback":{  
      "url":"https://s3.amazonaws.com/",
      "method":"POST"
   },
   "num_digits":10,
   "finish_on_key":"#",
   "digits_only":true,
   "timeout":10
}

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Stop Actions

Stops currently running actions on a call by ID. For example, stopping currently playing audio.

POST /LiveCalls/{call_id}/Actions/Stop

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
actions A comma-separated list of actions. Defaults to AUDIO. string No

Example Request

{
  "actions": "AUDIO"
}

Response

No Response Body

Response Codes

Status Description
204 Success returns no content.
4xx & 5xx General Error Codes

Leave Voicemail

Leaves a voicemail for the specified call by ID.

This method will attempt to wait for a beep before playing the message.

It allows the caller to transition to another call prior to ending the current call.

POST /LiveCalls/{call_id}/Actions/LeaveVoiceMail

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
message The voicemail message to leave. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array No

Example Request

{
    "message": "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3"
}

Response

No Response Body

Response Codes

Status Description
204 The content is empty on success.
4xx & 5xx General Error Codes

Tell

Plays TTS, Audio Files and/or DTMF tones to a specified caller by ID.

Only the specified caller will hear the messages. Allows developer to combine any or all message types in any order. This is most helpful when “stitching” together various audio files for highly personalized messages.

Supported voice files: MP3, OGG and WAV.

POST /LiveCalls/{call_id}/Actions/Tell

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
messages An array of TTS messages, url to audio files and/or DTMF tones. array Yes

Example Request

{  
   "messages":[  
      "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3",
      "1234 dollars and 56 cents.",
      "dtmf://123#"
   ]
}

Response

No Response Body

Response Codes

Status Description
204 The content is empty on success.
4xx & 5xx General Error Codes

Call Transfer

Transfers the specified call to the specified phone number or SIP endpoint by ID.

POST /LiveCalls/{call_id}/Actions/Transfer

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
message The message to play before the transfer. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string array
call The call object to connect. string Yes
call.no The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as [email protected] string Yes
call.caller_id_no The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). Defaults to the number of the caller that dialed your inbound number (caller_ no in your callbacks). string Yes

Example Request

{  
   "message":"https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3",
   "call":{  
      "no":"+17145551212",
      "caller_id_no":"+15625551212"
   }
}

Response

No Response Body

Response Codes

Status Description
204 The content is empty on success.
4xx & 5xx General Error Codes

Inject Actions List

Injects an array of ACTIONS into live calls. All CallFlows callback response Actions are supported.

POST /LiveCalls/{call_id}/Actions

Authentication Type

API Key (Application-level)

Request

Parameter Description Required Type
Actions An array of ACTIONS yes array

Example Request

[  
   {  
      "type":"SAY",
      "params":{  
         "text":"Welcome to our conference.",
         "loop":1
      }
   },
   {  
      "type":"CONFERENCE",
      "params":{  
         "name":"test-conf"
      }
   }
]

Response

No Response Body

Response Codes

Status Description
204 The content is empty on success.
4xx & 5xx General Error Codes

Modify Session Data

Write/overwrite session_data on a live call by ID.

This new session data will not change the unfinished ACTIONS being executed in the current callback.

The body must be a plain JavaScript object. This object will completely replace the current session data.

POST /LiveCalls/{call_id}/Actions/SessionData

Authentication Type

API Key (Application-level)

Request

Any valid JSON object up to 16k

Example Request

{
    "name": "Bob",
    "age": 25,
    "isNice": true
}

Response

No Response Body

Response Codes

Status Description
204 Returns empty content on success.
4xx & 5xx General Error Codes

Conferences

List Conferences

Returns the list of live conferences for this application.

GET /LiveCalls/Conferences

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Property Description Type
conferences Array of conferences. array
id The ID of the conference. string
name The name given to the conference. string
status The status of the conference: in-progress, on-hold. string
num_participants The number of participants currently in the conference. integer
participants An array of participants currently in the conference. array
participants[].id The ID of the participant. This is different than the call ID. string
participants[]call.id The ID of the caller. string
participants[]call.no The phone number of the caller. string
participants[]muted Is the participant on mute in this conference? boolean
participants[]on_hold Is the participant on hold in this conference? boolean
participants[]start_on_join The value of this conference parameter when the participant joined. boolean
participants[]hold_on_join The value of this conference parameter when the participant joined. boolean
participants[]end_on_exit The value of this conference parameter when the participant joined. boolean
participants[]hold_on_exit The value of this conference parameter when the participant joined. boolean

Example Response

{  
   "conferences":[  
      {  
         "id":"abc123",
         "name":"myConference",
         "status":"in-progress",
         "num_participants":10,
         "participants":[  
            {  
               "id":"xyz987",
               "call":{  
                  "id":"[email protected]",
                  "no":"+17145551212"
               },
               "muted":false,
               "on_hold":false,
               "start_on_join":false,
               "hold_on_join":false,
               "end_on_exit":false,
               "hold_on_exit":false
            }
         ]
      }
   ]
}

Response Codes

Status Description
200 Returns an array of conferences.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

View Conference Detail

Returns details about the specified conference.

GET /LiveCalls/Conferences/{conf_id}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
id The ID of the conference. string
name The name given to the conference. string
status The status of the conference: in-progress, on-hold. string
num_participants The number of participants currently in the conference. integer
participants An array of participants currently in the conference. array
participants[].id The ID of the participant. This is different than the call ID. string
participants[]call.id The ID of the caller. string
participants[]call.no The phone number of the caller. string
participants[]muted Is the participant on mute in this conference? boolean
participants[]on_hold Is the participant on hold in this conference? boolean
participants[]start_on_join The value of this conference parameter when the participant joined. boolean
participants[]hold_on_join The value of this conference parameter when the participant joined. boolean
participants[]end_on_exit The value of this conference parameter when the participant joined. boolean
participants[]hold_on_exit The value of this conference parameter when the participant joined. boolean

Example Response

{  
   "id":"abc123",
   "name":"myConference",
   "status":"in-progress",
   "num_participants":10,
   "participants":[  
      {  
         "id":"xyz987",
         "call":{  
            "id":"[email protected]",
            "no":"+17145551212"
         },
         "muted":false,
         "on_hold":false,
         "start_on_join":false,
         "hold_on_join":false,
         "end_on_exit":false,
         "hold_on_exit":false
      }
   ]
}

Response Codes

Status Description
200 Returns a conference object.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

View Participant Detail

Returns information about the specified participant of the specified conference.

GET /LiveCalls/Conferences/{conf_id}/Participants/{part_id}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
id The ID of the participant. This is different than the call ID. string
call.id The ID of the caller. string
call.no The phone number of the caller. string
muted Is the participant on mute in this conference? boolean
on_hold Is the participant on hold in this conference? boolean
start_on_join The value of this conference parameter when the participant joined. boolean
hold_on_join The value of this conference parameter when the participant joined. boolean
end_on_exit The value of this conference parameter when the participant joined. boolean
hold_on_exit The value of this conference parameter when the participant joined. boolean

Example Response

{  
   "participants":[  
      {  
         "id":"xyz987",
         "call":{  
            "id":"[email protected]",  
            "no":"+17145551212"
         },
         "muted":false,
         "on_hold":false,
         "start_on_join":false,
         "hold_on_join":false,
         "end_on_exit":false,
         "hold_on_exit":false
      }
   ]
}

Response Codes

Status Description
200 Returns a Participant object.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Join Conference

Places a caller into the specified conference.

POST /LiveCalls/{call_id}/Actions/Conference/Join

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
conference_name The name of the conference. Conference name is scoped to the application. To avoid unwanted behavior, use unique conference names. Accepts: alpha-numeric, dashes, and underscores. string Yes
message The message to play before joining the conference. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array No
join_muted If true, the participant will join the conference on mute. Default is false. boolean No
mute_on_key The key to press to mute one’s self. Default is “1”. string No
unmute_on_key The key to press to unmute one’s self. Default is “2”. string No
exit_on_key The key to press to leave the conference. Default is “#”. string No
async If true, this action will not block the call flow. Default is false. boolean No
max_participants The maximum number of participants allowed at one time. Join attempts that would exceed the max throw an error event. Default is Infinite. number No
hold_audio The URL to the audio file to play when a participant is placed on hold. If omitted, our default hold music will be used. string No

Example Request

{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3",
    "join_muted": true,
    "mute_on_key": "1",
    "unmute_on_key": "2",
    "exit_on_key": "3",
    "async": true,
    "max_participants": 50,
    "hold_audio": "https://myserver.com/conference-app/holdAdio.wav"
}

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Leave Conference

Forces the specified conference participant to leave a conference.

POST /LiveCalls/{call_id}/Actions/Conference/Leave

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
conference_name The name of the conference. string Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array No

Example Request

{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3"
}

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Mute Participant

Mutes the specified conference participant during a conference.

POST /LiveCalls/{call_id}/Actions/Conference/Mute

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
conference_name The name of the conference. string Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array No

Example Request

{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3"
}

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Unmute Participant

Unmutes the specified conference participant during a conference.

POST /LiveCalls/{call_id}/Actions/Conference/Unmute

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
conference_name The name of the conference. string Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array No

Example Request

{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3"
}

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Hold Participant

Places the specified conference participant on hold.

POST /LiveCalls/{call_id}/Actions/Conference/Hold

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
conference_name The name of the conference. string Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array No

Example Request

{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3"
}

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Resume Participant

Remove the specified conference participant from hold.

POST /LiveCalls/{call_id}/Actions/Conference/Resume

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
conference_name The name of the conference. string Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, and/or DTMF (example: dtmf://1234). Default is no message. string/array No

Example Request

{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.shoutpoint.music/classical/BusyStrings.mp3"
}

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Logs

List Call Logs

Returns a list of call logs which may be filtered by date, direction and connect time. A maximum of 1,000 logs can be returned. If more than 1,000 logs are found, is_truncated will equal true.

GET /Account/Logs/Calls?{query string}           // Account-level

Authentication Type

Basic Authentication (Account-level) OR API Key (Application-level)

GET /History/Logs/Calls?{query string}           // Application-level

Request Query

Name Description
begin_date The date of the earliest log to retrieve. Inclusive. The default value is one hour before now. Expects ISO 8601 format.
end_date The date of the most recent log to retrieve. Non-inclusive. The default value is NOW. Expects ISO 8601 format.
*app_id An application’s ID.
*subaccount_id An application’s Sub Account ID.
direction Accepts: inbound, outbound. Omitting this parameter will return both.
connect_time Returns logs with connect times (in seconds) greater than or equal to this amount.

Response

Property Description Type
is_truncated If the query finds more results than can be returned, this property is true. Solution: narrow your date range. boolean
begin_date The begin date of the search. ISO Date
end_date The end date of the search. ISO Date
logs An array of log objects. log[]
logs.id The ID of the log. string
logs.call_id The tried and true call ID. string
logs.api_no The phone number provisioned to the API (E.164 format: +17145551212). string
logs.caller_no The phone number of the caller (E.164 format: +17145551212). string
logs.start_time The time the call started. ISO Date
logs.end_time The time the call ended. ISO Date
logs.app_id The ID of the application the log belongs to. integer
logs.subaccount_id The Sub Account ID of the application the log belongs to. string
logs.type The type of call: voice or sms. string
logs.duration The length of the call in milliseconds. long
logs.status The call state. Codes: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. string
logs.connect_time_billed The multiplier of seconds billed. 1 = one second billed. float
logs.connect_time_sec The number of seconds the call was connected. integer
logs.origin_api The API the call interacted with. CallFlows, Dials_SMS, Notifications, etc. string
logs.text_message For SMS calls, this is the message sent to received. string
logs.config The CallFlows configuration at the time of this call. See POST /CallFlows/Callbacks for details. object

Example Response

{  
   "logs":[  
      {  
         "id":"xxx-yyy-zzz",
         "app_id":"aaa-bbb-ccc",
         "subaccount_id":"0",
         "call_id":"[email protected]",
         "caller_no":"+17145551212",
         "api_no":"+19495551212",
         "start_time":"2016-09-19T18:00:04.810Z",
         "end_time":"2016-09-19T18:00:18.985Z",
         "type":"voice",
         "direction":"inbound",
         "duration":14712,
         "status":"completed",
         "error":null,
         "connect_time_billed":0.2,
         "connect_time_sec":12,
         "origin_api":"CallFlows",
         "config":{  
            "no":"+19495551212",
            "callback":{  
               "method":"GET",
               "url":"http://s3.amazonaws.com/com.domain.www/actions.json",
               "content_type":"application/json"
            },
            "answer_on_ring":"1",
            "last_set_on":"2016-09-08T18:04:46.070Z"
         }
      }
   ],
   "begin_date":"2016-09-19T17:00:35.966Z",
   "end_date":"2016-09-19T18:00:35.966Z",
   "is_truncated":false
}

Response Codes

Status Description
200 Returns an array of call logs.
4xx & 5xx General Error Codes

List CallFlows Logs

Returns a list of calls by date that were handled by the CallFlows API.

GET /CallFlows/Logs?{query string}

Authentication Type

Basic Authentication (Account-level)

Request Query

Name Description
begin_date The date of the earliest log to retrieve. Inclusive. The default value is one hour before now. Expects ISO 8601 format.
end_date The date of the most recent log to retrieve. Non-inclusive. The default value is NOW. Expects ISO 8601 format.
page For paginations, the page number to return. This uses zero-based numbering. Default is 0.
page_size For pagination, the number of items to return per request. Max is 1000. Default is 100.

Response

The response is an array of call objects and pagination data. The object is defined below.

Parameter Description Type
logs An array of calls made via CallFlows. array
logs[].call A call object. object
logs[].call.id The ID if the call. string
logs[].call.no The phone number the call is connected to. string
logs[].call.caller_id_no The phone number of the caller. string
logs[].start_on The date and time the call began. string
logs[].end_on The date and time the call ended. string
logs[].json_response Does this call have JSON responses. boolean
logs[].ccml_response Does this call have CCML responses. boolean
logs[].error_response Did an error occur during this call. boolean
begin_date The starting date and time of the search. string
end_date The ending date and time of the search. string
page The current page of the search. Pages use zero-based numbering. integer
page_size The maximum number of calls returned in the request. integer

Example Response

{  
   "logs":[  
      {  
         "call":{  
            "id":"[email protected]",
            "api_no":"+15625551212",
            "caller_no":"+17145551212"
         },
         "start_on":"2016-09-07T19:14:39.000Z",
         "end_on":"2016-09-07T19:14:46.000Z",
         "json_response":true,
         "ccml_response":false,
         "error_response":false
      }
   ],
   "begin_date":"2016-09-07T18:15:14.717Z",
   "end_date":"2016-09-07T19:15:14.717Z",
   "page_size":100,
   "page":0
}

Response Codes

Status Description
200 Returns an array of call logs.
4xx & 5xx General Error Codes

View Call Flow Detail

Returns the callback-response loop information for the specified call.

GET /CallFlows/Logs/{call_id}

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Response

Parameter Description Type
call A call object. object
call.id The ID if the call. string
call.no The phone number the call is connected to. string
call.caller_id_no The phone number of the caller. string
start_on The date and time the call began. string
end_on The date and time the call ended. string
callbacks An array of callback data, requests and responses. array
callbacks[].requested_on The date and time the callback request was sent. date
callbacks[].request The actual request sent to the server. object
callbacks[].data The data of the call sent in the request. See /CallFlows/Callbacks. boolean
callbacks[].json The JSON, if any, in the server response. object
callbacks[].ccml The CCML sent to Shoutpoint. Either translated from the JSON response or the CCML response. string
callbacks[].error Any error that occurred during the callback. Not the errors during call execution. Try /CallFlows. string

Example Response

{  
   "call":{  
      "id":"[email protected]"
   },
   "start_on":"2016-09-07T19:14:39.000Z",
   "end_on":"2016-09-07T19:14:46.000Z",
   "callbacks":[  
      {  
         "requested_on":"2016-09-07T19:14:39.000Z",
         "data":{  
            "type":"init_call",
            "app_id":"29a471cc-4ada-4249-a7a5-5046464f9887",
            "call_id":"[email protected]",
            "start_time":"2016-09-07T19:14:34.167Z",
            "api_no":"+1565551212",
            "caller_no":"+17145551212",
            "duration":3719,
            "status":"live-in-progress",
            "key_presses":null,
            "last_queue_poll_connect_call":null,
            "custom_data":null,
            "session_data":null
         },
         "request":{  
            "url":"http://s3.amazonaws.com/com.shoutpoint/callback.json",
            "method":"GET",
            "content_type":"application/json",
            "headers":{  
               "Accept":"application/json;application/xml",
               "Accept-Encoding":"gzip",
               "Cache-Control":"no-cache",
               "Connection":"keep-alive",
               "Content-Type":"application/json",
               "Host":"s3.amazonaws.com",
               "Origin":"https://api.shoutpoint.com"
            },
            "content":""
         },
         "json":{  
            "actions":[  

            ]
         },
         "ccml":"<CCML></CCML>",
         "error":null
      }
   ]
}

Response Codes

Status Description
200 The callback-response loop details of the specified call.
4xx & 5xx General Error Codes

Messages

Send SMS

Creates and sends a single SMS message to a specified phone number.

The ‘call.caller_id_no’ must be a SMS-enabled number that is assigned to an inbound API.

Note: Errors will cause a call to be placed with an error message. Errors are likely due to an illegal call.caller_id_no.

POST /Dials/SMS

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call The SMS call object. string Yes
call.no The phone number to send the message to. string Yes
call.caller_id_no The phone number the message is from. Must be an assigned number. string Yes
message The SMS message. string Yes

Example Request

{  
   "call":{  
      "no":"+17145551212",
      "caller_id_no":"+15625551212"
   },
   "message":"Hello World"
}

Response

Parameter Description Type
call The SMS call object. string
call.id The ID of the message. string
call.no The phone number to send the message to. string
call.caller_id_no The phone number the message is from. Must be an assigned number. string

Response Codes

Status Description
201 Returns a call object.
4xx & 5xx General Error Codes

Payments

Make Payment

Make a credit card payment to increase your balance.

Payment methods (credit card, Paypal) can only be added in the Portal, but once you have added a payment method, you can make payments via this method

POST /Account/Payments

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
amount The amount to be charged. number Yes
description Override the default description with this custom string. string No
payment_method The payment method to be used. Omitting this property will charge the default payment method. object No
payment_method.token If payment_method is included, this property is required. string Yes
payment_method.method The method type, like 'Credit Card’. Used to generate default description. string No
payment_method.card_type The type of credit card. Visa, Master Card, American Express, etc. Used to generate default description. string No
payment_method.last_four The last four digit of the credit card number. Used to generate default description. string No

Response

Property Description Type
id Payment ID number
transaction_id Transaction ID (from payment processor) number
submitted_on Datetime of transaction. ISO Date string
amount Amount of payment. number
description User-definable description of payment. string

Example Response

{
  "id": 123,
  "transaction_id": 12345,
  "submitted_on": "2016-09-07T17:27:23.486Z",
  "amount": 20.00,
  "description": "Payment via Dev Portal"
}

Response Codes

Status Description
200 Success returns a transaction object.
4xx & 5xx General Error Codes
4xx & 5xx Payment Error Codes

List Payment Methods

Returns the available payment methods assigned to an account.

GET /Account/Payments/Methods

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Response

Property Description Type
payment_methods array
token Unique Method ID string
method Method type (Credit Card) string
card_type Type of card. string
last_four Last four digits of card number. string
is_default Is this the default payment method. boolean
created_on The datetime the method was added. ISO Date string
updated_on The datetime the method was last updated. ISO Date string
is_expired Is the method expired? boolean

Example Response

{  
   "payment_methods":[  
      {  
         "token":"6g6kpg",
         "method":"Credit Card",
         "card_type":"American Express",
         "last_four":"0005",
         "is_default":false,
         "created_on":"2016-03-16T10:09:00.000Z",
         "updated_on":"2016-03-16T12:49:00.000Z",
         "is_expired":false
      },
      {  
         "token":"5fvy2r",
         "method":"Credit Card",
         "card_type":"MasterCard",
         "last_four":"5100",
         "is_default":false,
         "created_on":"2016-03-16T09:53:00.000Z",
         "updated_on":"2016-03-16T09:53:00.000Z",
         "is_expired":false
      },
      {  
         "token":"dtcsyg",
         "method":"Credit Card",
         "card_type":"Visa",
         "last_four":"1111",
         "is_default":true,
         "created_on":"2016-03-15T13:27:00.000Z",
         "updated_on":"2016-03-15T13:28:00.000Z",
         "is_expired":false
      }
   ]
}

Response Codes

Status Description
200 A successful response return payment methods.
4xx & 5xx General Error Codes
4xx & 5xx Payment Error Codes

List Payment History

Returns payments history by date range.

GET /Account/Payments

Authentication Type

Basic Authentication (Account-level)

Request Query

Name Description
begin_date Set this parameter to the date/time to begin the query. ISO 8601 date format is required.
end_date Set this parameter to the date/time to begin the query. ISO 8601 date format is required.

Response

Property Description Type
payments Array of payments array
payments[].id Payment ID number
payments[].transaction_id Transaction ID (from payment processor) number
payments[].submitted_on Datetime of transaction. ISO Date string
payments[].amount Amount of payment. number
payments[].description User-definable description of payment. string

Example Response

{  
   "payments":[  
      {  
         "id":1619,
         "submitted_on":"2016-03-15T21:27:11.000Z",
         "amount":100,
         "description":"Credit Card American Express 0005 via api.shoutpoint.com"
      },
      {  
         "id":1621,
         "submitted_on":"2016-03-15T21:28:04.000Z",
         "amount":50,
         "description":"Default method via api.shoutpoint.com"
      },
      {  
         "id":1627,
         "submitted_on":"2016-03-16T01:00:03.000Z",
         "amount":20,
         "description":"Credit Card American Express 0005 via api.shoutpoint.com"
      }
   ]
}

Response Codes

Status Description
200 Success returns an array of payments.
4xx & 5xx General Error Codes
4xx & 5xx Payment Error Codes

Phone Numbers

List Available Inbound Numbers

Returns a list of phone numbers available for provisioning and purchase.

GET /PhoneNumbers/Available?{query string}

Authentication Type

API Key (Application-level)

Request Query

Name Description
is_sms (required) Set this parameter to true to return SMS-enabled numbers. Higher fees may apply.
is_toll_free Set this parameter to true to return non-prefix specific toll-free numbers. If set to true, all search_by and search_on will be ignored. For prefix specific toll-free searches, ignore this parameter, set the search_by to prefixes, and pass a three-digit toll free area code(s) into search_on. Most toll free numbers do not support SMS.
max_results Sets the number of results to return. Max value is 500. Default is 10.
search_by Search by this criteria. Accepts region, prefixes, postal-code, rate-center, latas. Default is region.
search_on The value to search for, based on the search_by parameter. See search_on details in the next table.

Search criteria

search_by search_on Details
region Accepts state or city and state. Separate city and state by a comma. Examples: “Irvine” and “Irvine, CA”.
prefixes Accepts a comma-delimited list of area codes. Example: “714,310,949”.
postal-code Accepts a five digit postal code.
rate-center Accepts rate center name and state. Example: NEWPORTBCH, CA.
latas Accepts a comma-delimited list of latas. Example: “123,456,789”.

Response

Property Description Type
phone_numbers List of phone numbers. array
phone_numbers[].no Phone number in E.164 format. string
phone_numbers[].formatted A human-friendly phone number format. string

Example Response

{
  "phone_numbers": [
    {
      "no": "+19495551212",     
      "formatted": "(949) 555-1212"
    },
    {
      "no": "+19495551213",
      "formatted": "(949) 555-1213"
    },
    {
      "no": "+19495551214",
      "formatted": "(949) 555-1214"
    }
  ]
}

Response Codes

Status Description
200 An array of available phone numbers.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

List Provisioned Numbers

Returns a list of phone numbers assigned to CallFlows and/or ParkingLot. Omit /{assigned_to to get all assigned numbers.

GET /PhoneNumbers/{assigned_to}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Property Description Type
phone_numbers List of phone numbers. array
phone_numbers[].no The phone number in E.164 format. string
phone_numbers[].formatted A human-friendly phone number format. string
phone_numbers[].assigned_to Which API this number is assigned to. NULL for available numbers. null
phone_numbers[].error Any error that occurred when provisioning the number. string
phone_numbers[].capabilities[] Features supported by the phone number: voice_inbound, voice_outbound, sms_inbound, sms_outbound, 'cnam’ array
phone_numbers[].description User-definable description of the phone number. string
phone_numbers[].caller_id_name If cnam capable, the name of the phone number’s owner. string
phone_numbers[].price The fee for using this number. number
phone_numbers[].price_period The recurring period the price will be charged: month. string
phone_numbers[].usage The number of calls made for the lifetime of the phone number. number

Example Response

{
    "phone_numbers": [
        {
            "no": "+17145551212",
            "formatted": "(714) 555-1212",
            "assigned_to": "CallFlows",
            "is_routed": true,
            "description": "Office Desk Phone",
            "capabilities": [
                "sms_inbound",
                "sms_outbound",
                "voice_inbound",
                "voice_outbound"
            ],
            "caller_id_name": "Bob Jones",
            "status": "routed",
            "usage": 100,
            "price": 1,
            "price_period": "month"
        }
    ]
}

Response Codes

Status Description
200 An array phone number objects.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Provision Phone Numbers

Purchase and assign phone numbers to CallFlows or ParkingLot.

POST /PhoneNumbers/{assigned_to}

Authentication Type

API Key (Application-level)

Request

Property Description Type
phone_numbers List of phone numbers. array
phone_numbers[].no Phone number in E.164 format. string

Note: The API will except the complete phone_numbers object returned by GET /PhoneNumbers/Available. However, only no is required.

Example Request

{
  "phone_numbers": [
    {
      "no": "+19495551212"
    },
    {
      "no": "+19495551213"
    },
    {
      "no": "+19495551214"
    }
  ]
}

Response

Property Description Type
phone_numbers[] List of assigned phone numbers. array
phone_numbers[].no Phone number in E.164 format. string
phone_numbers[].formatted A human-friendly phone number format. string
phone_numbers[].is_routed If true, the number has been added with no errors. boolean
phone_numbers[].error Only included if is_routed is false. string

Example Response

{  
   "phone_numbers":[  
      {  
         "no":"+1535551212",
         "formatted":"(530) 555-1212",
         "assigned_to": "CallFlows",
         "is_routed": true,
         "error": "If in error state, the error description will appear here."

      }
   ]
}

Response Codes

Status Description
200 Returns all the phone numbers under this assigned_to.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Update Phone Numbers

Update a phone number’s description and/or caller_id_name.

PUT /PhoneNumbers/{no}

Authentication Type

API Key (Application-level)

Request

Property Description Type
description User-definable description of the phone number. string
caller_id_name If cnam capable, the name of the phone number’s owner. string

Example Request

{
  "description": "Mobile Phone",     
  "caller_id_name": "Jane Doe"
}

Response

Property Description Type
no The phone number in E.164 format. string
formatted A human-friendly phone number format. string
assigned_to Which API this number is assigned to. NULL for available numbers. null
error Any error that occurred when provisioning the number. string
capabilities Features supported by the phone number: voice_inbound, voice_outbound, sms_inbound, sms_outbound, cnam array
description User-definable description of the phone number. string
caller_id_name If cnam capable, the name of the phone number’s owner. string
price The fee for using this number. number
price_period The recurring period the price will be charged: month. string
usage The number of calls made for the lifetime of the phone number. number

Example Response

{
  "no": "+17145551212",
  "formatted": "(714) 555-1212",
  "assigned_to": "CallFlows",
  "description": "Office Desk Phone",
  "capabilities": [
    "sms_inbound",
    "sms_outbound",
    "voice_inbound",
    "voice_outbound"
  ],
  "caller_id_name": "Bob Jones",
  "status": "routed",
  "usage": 100,
  "price": 1,
  "price_period": "month"
}

Response Codes

Status Description
200 The details of the updated phone number.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Release Phone Numbers

Releases phone numbers from CallFlows or ParkingLot. This will make the phone numbers available to all again. If you’d like to hang on to the phone numbers, assign them to ParkingLot.

DELETE /PhoneNumbers/{assigned_to}

Authentication Type

API Key (Application-level)

Request

Property Description Type
phone_numbers List of phone numbers. array
phone_numbers[].no Phone number in E.164 format. string

Note: The API will except the complete phone_numbers object returned by GET /PhoneNumbers/{assigned_to}. However, only no is required.

Example Request

 {
  "phone_numbers": [
    {
      "no": "+19495551212"
    },
    {
      "no": "+19495551213"
    },
    {
      "no": "+19495551214"
    }
  ]
}

Response

No content.

Response Codes

Status Description
204 No content is returned on success.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Queues

List Queues

Returns a list of Call Queues.

GET /LiveCalls/Queues

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Property Description Type
queues A list of available queues. array
queues.name The queue’s unique name. string
queues.hold_times Hold time stats for the queue. object
queues.hold_times.estimated The estimated hold time in seconds. number

Example Response

{
   "queues": [
      {
         "name": "name_of_queue",
         "hold_times": {
            "estimated": 1.234
         }
      }
   ]
}

Response Codes

Status Description
200 Returns a list of queues.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

View Queue Details

Returns the details of a queue.

GET /LiveCalls/Queues/{queue_name}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Property Description Type
name The queue’s unique name. string
hold_times Hold time stats for the queue. object
hold_times.estimated The estimated hold time in seconds. number

Example Response

{
   "name": "name_of_queue",
   "hold_times": {
      "estimated": 1.234
   }
}

Response Codes

Status Description
200 Returns queue detail.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

List Queued Calls

Returns all of the calls in the specified queue.

GET /LiveCalls/Queues/{queue_name}/Calls

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
calls An array of queued calls, sorted from first to last. array
calls.call The call object. . object
calls.call.id The unique ID for the call. string
calls.call.no The phone number for the call. string
calls.call.caller_id_no The phone number provisioned to the application. string
calls.queued_on The date and time the call was queued in ISO 8601. string
calls.hold_time The number of seconds the call has been queued. number
calls.position The position of the call in the queue. integer
queue_name The name of the queue. string
hold_times A group of hold time data. object
hold_times.average The average hold time of all current calls. This is not estimated hold time. number
hold_times.least The lowest current hold time. number
hold_times.greatest The highest current hold time. number

Example Response

{
   "calls": [
      {
         "call": {
            "id": "[email protected]",
            "no": "+17145551212",
            "caller_id_no": "+19495551212"
         },
         "queued_on": "2017-02-16T17:16:11.597Z",
         "hold_time": 30.123,
         "position": 1
      }
   ],
   "queue_name": "name_of_queue",
   "hold_times": {
      "average": 1.23,
      "least": 10.123,
      "greatest": 45.678
   }
}

Response Codes

Status Description
200 A list of queued calls.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

View Queued Call Detail

Returns the details of a queued call.

GET /LiveCalls/Queues/{queue_name}/Calls/{call_id}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Parameter Description Type
id This ID is unique to the queue. Do not confuse this with the regular call id. string/array
call The call object. object
call.id The classic call ID. string
call.no The phone number for the call. string
call.caller_id_no The phone number provisioned to the application. string
queued_on The date and time the call was queued in ISO 8601. string
hold_time The number of seconds the call has been queued. number
position The position of the call relevant to other calls in the queue. integer

Example Response

{
   "id": "abc123",
   "call": {
      "id": "[email protected]",
      "no": "+17145551212",
      "caller_id_no": "+19495551212"
   },
   "queued_on": "2017-02-16T17:16:11.597Z",
   "hold_time": 30.123,
   "position": 3
}

Response Codes

Status Description
200 Returns the queued call detail.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Peek at Queue

Returns the next call in the queue. Peek does not remove the queued call.

GET /LiveCalls/Queues/{queue_name}/Peek

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Property Description Type
id This ID is unique to the queue. Do not confuse this with the regular call id. string
call The call object. object
call.id The classic call ID. string
call.no The phone number for the call. string
call.caller_id_no The phone number provisioned to the application. string
queued_on The date and time the call was queued in ISO 8601. string
hold_time The number of seconds the call has been queued. number
position The position of the call relevant to other calls in the queue. integer

Example Response

{  
   "id": "abc123",
   "call":{  
      "id":"1234",
      "no":"9991112222"
   },
   "queued_on":"2016-09-15T15:53:00",
   "hold_time":60,
   "position":5
}

Response Codes

Status Description
200 Returns the queued call’s details.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Poll Queue

Returns the next call from the queue. The call will then continue to execute its regular call flow.

This request will block/long poll for up to 15 seconds on an empty queue. To avoid blocking, PEEK then POLL.

GET /LiveCalls/Queues/{queue_name}/Poll

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Property Description Type
id This ID is unique to the queue. Do not confuse this with the regular call id. string
call The call object. object
call.id The classic call ID. string
call.no The phone number for the call. string
call.caller_id_no The phone number provisioned to the application. string
queued_on The date and time the call was queued in ISO 8601. string
hold_time The number of seconds the call has been queued. integer

Example Response

{  
   "call":{  
      "id":"1234",
      "no":"9991112222"
   },
   "queued_on":"2016-09-15T15:53:00",
   "hold_time":60,
   "position":5
}

Response Codes

Status Description
200 Returns the dequeued call’s details.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Remove Queued Call

Deletes the specified call from the queue, regardless of position. When the call exits, it will continue its normal call flow.

DELETE /LiveCalls/Queues/{queue_name}/Calls/{call_id}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

No Response Body

Response Codes

Status Description
204 A successful request returns empty content.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Delete Queue

Deletes the specified queue. Any queued calls will be released to continue their regular call flows. A deleted queue will not appear in the list of queues. To recreate the queue, simply offer a call.

DELETE /LiveCalls/Queues/{queue_name}

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

Property Description Type
name The queue’s unique name. string
hold_times Hold time stats for the queue. object
hold_times.estimated The estimated hold time in seconds. number

Example Response

{  
   "name":"myQueue",
   "hold_times":{  
      "estimated":360
   }
}

Response Codes

Status Description
200 Returns the deleted queue’s details.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Recordings

Start Recording

Creates a call recording.

POST /LiveCalls/{call_id}/Actions/Recording/Start

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
group A queryable name for the recording. string No
message The message to place after recording has started. string/array No
pre_message The message to play before the recording has started. string/array No

Example Request

{
    "group": "support_technical",
    "pre_message": "This call is about to be recorded.",
    "message": "This call is now being recorded."
}

Response

No Response Body

Response Codes

Status Description
204 Success returns empty content.
4xx & 5xx General Error Codes

Pause Recording

This method allows developers to pause a call recording. This is useful for when it’s desirable to excerpt portions of a conversation while generating one audio file.

POST /LiveCalls/{call_id}/Actions/Recording/Pause

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

No Response Body

Response Codes

Status Description
204 Success returns empty content.
4xx & 5xx General Error Codes

Resume Recording

This method allows developers to resume a paused call recording.

POST /LiveCalls/{call_id}/Actions/Recording/Resume

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

No Response Body

Response Codes

Status Description
204 Success returns empty content.
4xx & 5xx General Error Codes

Stop Recording

This method allows developers to stop a call recording.

POST /LiveCalls/{call_id}/Actions/Recording/Stop

Authentication Type

API Key (Application-level)

Request

No Request Body

Response

No Response Body

Response Codes

Status Description
204 Success returns empty content.
4xx & 5xx General Error Codes

List Recordings

Returns a filtered list of recordings across all applications.

A maximum of 1,000 recordings can be returned per request. If is_truncated indicates that more recordings were available, narrow your date range.

GET /Account/Recordings?{query string}           // Account-level

Authentication Type

Basic Authentication (Account-level) OR API Key (Application-level)

GET /History/Recordings?{query string}           // Application-level

Request Query

Name Description
begin_date Set the earliest recording to return by date/time in ISO 8601 format. Default: one hour before now.
end_date Set the latest recording to return by date/time in ISO format. Default: now.
group Returns all recordings with the specified group value set in the Record action. Default: audio_recording.
app_id Returns all recordings for the given application ID. *
subaccount_id Returns all recordings for the given application Sub Account ID. *
call_no Returns all recordings originated with the given phone number. Expects E164 format.
call_id Returns all recordings originated on the given call id.
direction Returns recordings based on the originating call’s direction. Omit to include all.

Response

Property Description Type
is_truncated If the query finds more results than can be returned, this property is true. boolean
recordings An array of recording objects. recording[]
recordings.id The ID of the recording. string
recordings.app_id The ID of the application used for this call. string
recordings.subaccount_id The Sub Account ID of the application used for this call. integer
recordings.group The user-defined group. string
recordings.call_id The tried and true call ID. string
recordings.caller_no The phone number of the originating caller (E.164 format: +17145551212). string
recordings.start_time The time the recording started. date
recordings.end_time The time the recording ended. date
recordings.duration The length of the recording in milliseconds. long

Example Response

{  
   "recordings":[  
      {  
         "id":"MTMwMDE1QDQ2OjViOTyMzY3YjRkMDdjNHwx",
         "app_id":"eaffd4-1234-4a95-9876-9c0b8",
         "subaccount_id":"0",
         "group":"audio_recording",
         "call":{  
            "id":"[email protected]",
            "no":"+17145551212"
         },
         "start_time":"2016-03-29T22:05:32.000Z",
         "end_time":"2016-03-29T22:05:34.249Z",
         "duration":2249
      }
   ],
   "is_truncated":false
}

Response Codes

Status Description
200 Returns an array of recoding objects.
4xx & 5xx General Error Codes

Download Recording

Returns downloaded audio files of recordings. Available formats: ulw, vox, mp3, wav, wavM, ogg, aac, au.

GET /Account/Recordings/{id}/{format}

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Response

Audio File

Response Codes

Status Description
200 Returns a data stream of the requested audio file.
4xx & 5xx General Error Codes

Variables

Shoutpoint’s JSON Call Flow Actions support the use of variables much like traditional programming languages. In fact, our variables and expressions are evaluated by an ES5 JavaScript engine. All basic JavaScript data types (string, number, boolean, array and object) are supported. Expressions are evaluated as one would expect in JavaScript.

Here are some notable details to keep in mind:

Native Constants

For convenience, some constants are made available with data about the call. These are assigned to variables and are listed below. These variables are read-only and any attempts to change their values will fail silently.

Variable Name Type Description
$config object The callback configuration object set with the /CallFlows/Callbacks request.
$lastQueuePollConnectCall object The last call bridged with a QUEUE poll_connect. Includes properties id and no.
$direction string Indicates if the call is INBOUND or OUTBOUND
$keyPresses string The last key presses collected by the COLLECT action. To check for no keys pressed, use $keyPresses == ''.
$isDebugMode boolean True if the call was initiated in debug mode.
$isInitCall boolean True if this is the first callback of the call.
$now number The current timestamp in milliseconds.
$callTime number The duration of the call in milliseconds.
$startTime number The start timestamp of the call in milliseconds.
$numConferenceParticipants string The number of participants in the last conference referenced by the CONFERENCE action during the call. Do not use before a conference has been accessed by the action to avoid a terminal error.
$callId string The unique ID of the call.
$appId string The unique ID of the application.
$collectAttempt number This variable counts how many times a call has visited each COLLECT action, starting with 1. This counter makes it easy to retry a COLLECT with IF and GOTO actions.
$callerNo string The phone number of the connected (or far end) call (E.164 format: +17145551212).
$callerNoRegion string The two-character region (state) code of the connected call’s phone number. Possibly null.
$callerNoCountry string The two-character country code of the connected call’s phone number. Possibly null.
$callerNoTimeZone string The time zone of the connected call’s phone number (America/Los_Angeles). Possibly null. Click here for list of time zones.
$apiNo string The provisioned (or near end) phone number of the API connected to the call (E.164 format: +17145551212).
$apiNoRegion string The two-character region (state) code of the API phone number. Possibly null.
$apiNoCountry string The two-character country code of the API phone number. Possibly null.
$apiNoTimeZone string The time zone of the API phone number (America/Los_Angeles). Possibly null. Click here for list of time zones.

User Defined Variables

In addition to the special writable variables $sessionData and $webhookData, you are free to create your own local variables using any of the supported data types (string, number, boolean, array and object).

Variable Name Type Description
$sessionData object The session_data set in the /Dials/Connect request and/or the DIALS and SESSIONDATA actions.
$webhookData object When a WEBHOOK action returns a JSON response, it is available via this variable. Default: undefined.

Variable Handling

Using variables in Shoutpoint’s JSON Call Flow Actions is very straight-forward once you get the hang of it. Variable assignment is done with a “special” JSON Action. This action is simplified to make variable handling as pleasant as possible in JSON.

Tutorial

The JSON KEY is the name of the variable and the JSON VALUE is the expression to evaluate. The right-side JSON value MUST ALWAYS be a STRING.

Basically, take a regular JavaScript variable assignment:

Change the = to a : and wrap both sides in double-quotes (with the necessary escaping) to make it JSON-friendly:

String assignment as done in plain JavaScript:

String assignment as done in a JSON Action (notice the nested quoting):

While it is tempting (since it is legal JSON) to try assigning basic data types like this:

It will not work! Remember, the right-side value is actually an expression that is evaluated. This lets us do things like this:

In the above example, notice how multiple variables are handled in one JSON Action object. This is legal, however assignment order is NOT guaranteed. If assignment order is critical, seperate the assignmnets into their own objects as array order is guaranteed:

Examples

Example User Defined Variables

{  
   "actions":[  
      {  
         "type":"SAY",
         "params":{  
            "text":"We're about to assign some variables."
         }
      },
      {  
         "$conferenceName":"'MyConference'",
         "$sessionData.isInConference":"true",
         "$counter":"0",
         "$myObj":"{}",
         "$myPets":"['Whiskers', 'Spot', 'Bubbles']",
         "$myPetsAgain":"{cat: 'Whiskers', dog: 'Spot', fish: 'Bubbles'}"
      },
      {  
         "$conferenceName":"'MyConference' + $counter"
      },
      {  
         "$sessionData.isInConference":"false"
      },
      {  
         "$myObj.foo":"'bar'"
      },
      {  
         "$counter":"$counter + 1"
      },
      {  
         "$myDog":"$myPets[1]"
      },
      {  
         "$myPetsAgain.bird":"'Tweety'"
      }
   ]
}
Variable:Expression Comment
“$conferenceName”:“'MyConference’” Notice how the MyConference string must use inner single-quotes.
“$sessionData.isInConference”:“true” Update individual properties in an object.
“$counter”:“0” Numbers, booleans, arrays and objects must be in quotes.
Variable:Expression Comment
“$conferenceName: ”'MyConference’ + $counter" Updates $conferenceName to “myConference0”.
“$sessionData.isInConference: "false” Updates $sessionData.isInConference to false.
“$myObj.foo”: “'bar’” Updates a previously initialized object.
“$counter”: “$counter + 1” Incerements $counter by one.
“$myDog”; “$myPets[1]” Assigns value at index 1 (“Spot”) to $myDog.
“$myPetsAgain.bird”: “'Tweety’” Adds new key/value to $myPetsAgain.

String Interpolation

It is possible to dynamically use variables in SAY “text” and PLAY “url” properties. To place a variable for interpolation, write it like so: ${sessionData.firstName} or ${callNo}. These will be parsed live.

In scope variables:

The in-scope variables are the same as those available to the IF action, with these additions:

Variable Type Description
$keyPressesSay String The keys from the last COLLECT spoken separately.
$callerNoSay String The phone number of the connected call spoken as (714) 555-1212.
$apiNoSay String The provisioned phone number of the API connected to the call spoken as (714) 555-1212.

Example String Interpolation

{  
   "actions":[  
      {  
         "type":"SAY",
         "params":{  
            "text":"Hello, ${sessionData.firstName}. Welcome to our conference.",
            "repeat":1
         }
      },
      {  
         "type":"CONFERENCE",
         "params":{  
            "name":"myConference"
         }
      },
      {  
         "type":"SAY",
         "params":{  
            "text":"You have left the conference. This call lasted ${callTime} milliseconds."
         }
      }
   ]
}

Errors

General Errors

Status Code Message Help User_message
400 400001 Validation Error [Custom Message with what failed validation] [Custom Message]
400 400010 Parsing Error [Custom Message] A 3rd party service could not understand our request.
400 400999 [Custom Message] It appears that the request was invalid. Check the ‘message’ property for more detail. A 3rd-party service could not understand your request. This could be due to submitting invalid data.
401 401001 Failed Authentication The X-API-Key header is missing or invalid. We are having trouble accessing a 3rd Party service.
401 401002 Failed Authentication Username and password are missing for basic auth. We are having trouble accessing a 3rd Party service.
403 403001 Forbidden Requests must be made through https://api.shoutpoint.com. The specified phone number(s) were not assigned.
402 402001 Insufficient Funds Your account balance is too low. Please make a payment to resume service. A 3rd-party service could not complete the request. Report code 402001 to customer support.
404 404001 Not Found The endpoint you are trying to access does not exist. Check your code for typos. Review our docs. We are having trouble accessing a 3rd Party service.
404 404002 Not Found The requested resource path or method is not supported. The resource we attemted to access no longer exists.
405 405001 Method Not Found This API does not support the X method.
500 500990 [Custom Message] It appears that our upstream server threw an internal error. You will likely need to contact support to clear this up. A 3rd-party service could not process your request.
500 500991 Server Error [Custom Message] A 3rd party service failed to handle our request.
500 500999 Uncaught Error: [fault.name]; [fault.type]; [fault.category] This error occurred in our proxy layer. Check the message for details and contact support if the error continues. A 3rd-party service returned an unexpected error.
500 500911 Fatal System Error [Custom Message] Contact Support. [Custom Message]

Caller ID Errors

Status Code Message Help User_message
404 404254 Not Found The Call ID Number does not exist in your application. It may have been removed or never added. The Caller ID Number could not be found.

Call Flow Errors

Status Code Message Help User_message
404 404101 Not Found There is no log with the given ID. If you are certain that the ID is correct, please contact support. The requested log could not be found.
500 500101 Storage Error [Custom Message] [Custom Message]
500 500102 Database Error [Custom Message] [Custom Message]

Conference Errors

Status Code Message Help User_message
404 404701 Not Found The conference may have been empty too long and destroyed. The requested conference participant was not found.
404 404702 Not Found The participant may not be in the conference any longer. The requested conference participant was not found.

Integration Errors

Status Code Message Help User_message
404 404504 Not Found There is no webhook by the given ID. The webhook config could not be found.
429 426501 Too Many Requests A webhook can only be executed once every 60 seconds. A webhook can only be executed once every 60 seconds.
500 500501 Storage Error [Custom Message] [Custom Message]

Payment Errors

Status Code Message Help User_message
400 400300 Payment was not successful: [Reason] Please provide a valid payment method. Payment was not successful: [Reason]

Phone Number Errors

Status Code Message Help User_message
400 400200 Bad Request The numbers are already assigned to the API. The specified phone number(s) are already assigned to this API.
400 400201 Bad Request None of the numbers are assigned to this API. No phone numbers could be released. No numbers are assigned to this API.
400 400202 Bad Request The /PhoneNumbers/_ resource does not support phone number provisioning. A 3rd-party service could not understand your request. This could be due to submitting invalid data.
400 400203 Bad Request [Custom Message] The search was invalid. This is likely due to an invalid combination of search criteria.
423 423001 Concurrent Request Error Provisioning and releasing phone numbers does not support concurrent requests per API Key. On status 423, try again after a few seconds. Our service was busy modifying phone numbers. Please try again.
500 500200 Server Error Updating the phone numbers list failed. This likely means that nothing has changed. Verify by pulling the list to check for changes. The specified phone number(s) were not assigned.
500 500201 Database Error The numbers were updated, but DB syncing failed. This error will not affect your applications. The specified phone number(s) were updated with non-fatal errors.

Queue Errors

Status Code Message Help User_message
404 404711 Not Found The queue ID may be wrong or the queue could have been garbage collected. The requested queue was not found.
404 404712 Not Found The call is not in the queue. It may have left the queue already. The requested queued call was not found.
404 404713 Not Found The queue is empty. No call was found. The queue is empty. No call was found.

Message Errors

Status Code Message Help User_message
404 404301 Not Found Session Data for this phone number does not exist. Set Session Data when sending a message. A 3rd-party service failed to process the message. Too much time may have passed since the last message.

Sub Account Errors

status code message help User_message
404 404801 Not Found The Sub Account ID is incorrect. A Sub Account by that ID never existed under this application. A 3rd-party service could not find the requested resource.
404 404802 Not Found The Sub Account ID references a Sub Account that no longer exists. A 3rd-party service reports that the requested resource is no longer available.

Live Calls Errors

status code message help User_message
404 404404 Not Found The Call ID is incorrect or the call ended and is longer available via LiveCalls. A live call could not be found with the ID provided.