Call Scheduling

Overview

This endpoint allows you to schedule calls which use a Summit application, or view a list of all your scheduled calls. You can POST to this to schedule a call or multiple calls using Summit Applications. You can also GET this endpoint to return a list of all scheduled calls, along with various diagnostic information about those scheduled calls.

This endpoint is rate limited, with the default rate of 1 call per second per domain. This can be changed: contact us if you need a higher rate. This rate limiting only affects calls scheduled through this REST API. It has no effect on inbound calls or calls initiated in other ways.

We also can’t guarantee that calls will happen precisely at the scheduled time. Calls will be sent in a small window on or after the scheduled time (assuming they are not over the rate limit).

Authentication

The Summit REST API uses HTTP Basic Authentication. You can generate an API key and secret at platform.corvisacloud.com, in Access > API Keys.

Endpoint URL

https://api.us1.corvisa.io/call/schedule

Both GET and POST are allowed on this endpoint. GET returns a list of scheduled calls, while POST schedules a new call (or multiple new calls).

POST

Headers

Content-Type: application/json

Content Body

Your request should look as follows:

{
    "destinations": DESTINATIONS,
    "internal_caller_id_number":CID_NUMBER,
    "internal_caller_id_name": CID_NAME,
    "destination_type": DESTINATION_TYPE,
    "destination_timeout": DESTINATION_TIMEOUT,
    "schedule": SCHEDULE,
    "application": APPLICATION_NAME,
    "application_destination": APPLICATION_DESTINATION,
    "application_data": APPLICATION_DATA,
    "external_caller_id_number": EXTERNAL_NUMBER,
    "log_src": LOG_SRC,
    "log_dst": LOG_DST,
    "channel_internal_caller_id_number": CHANNEL_INTERNAL_CALLER_ID_NUMBER,
    "channel_internal_caller_id_name": CHANNEL_INTERNAL_CALLER_ID_NAME,
    "channel_external_caller_id_number": CHANNEL_EXTERNAL_CALLER_ID_NUMBER,
    "destination_allow_outbound_route_caller_id": DESTINATION_ALLOW_OUTBOUND_ROUTE_CALLER_ID,
    "channel_allow_outbound_route_caller_id": CHANNEL_ALLOW_OUTBOUND_ROUTE_CALLER_ID
}

Note that we only accept JSON.

Fields

  • destinations Required (JSON): This is a list of destinations for the call. It should be a list of strings. If your destination_type is “endpoint”, then the destinations need to match auth_contact values for registered SIP endpoints. If your destination_type is “outbound”, then your destinations need to match one of the patterns in your outbound routes. Examples of “outbound” destinations would be any ten-digit phone number that you could dial from anywhere.
  • destination_timeout Optional (integer): This is the timeout for the initial call. We will only ring the specified destination for this many seconds. Default is 30 seconds.
  • internal_caller_id_number Required (string): This number appears as the caller ID number. We do not validate against real numbers.
  • internal_caller_id_name Required (string): This appears as the caller ID name.
  • destination_type Required (string): Valid choices are “outbound” or “endpoint”. If this is “outbound”, then destination will be attempted to be matched against your outbound routes. If this is “endpoint”, destination should correspond to an endpoint.
  • schedule Optional (string): Defaults to null. If this is not specified, the call will be scheduled as soon as possible (taking rate limiting into account). Otherwise, there are multiple formats for this: #1 – “+5 seconds”, “+2 minutes”, etc.: An offset for when to place the call. Valid options are: second, minute, hour, day, week, month, year., #2 – “YYYY-mm-dd HH:MM:SS+HH:MM” (ex: “2014-09-01 10:25:13+05:00”): A full timestamp (including timezone offset at the end, represented by the last hh:mm) of when to place the call.
  • application Optional (string): The Summit Application to run. By default, we will call an application called dial, which simply calls channel.dial(APPLICATION_DESTINATION), and expects APPLICATION_DESTINATION to be a routepoint or external number. We also provide an application called endpoint, which simply dials an endpoint instead of a route. If you want to call your own custom app, you can specify it by name here.
  • application_destination Optional (string): This parameter is passed along to the Summit Application. It’s available to that application in the summit.application library, by calling the get_destination function. This field is the same as setting up a Routepoint with a value in application_destination.
  • application_data Optional (string|JSON): This parameter works like application_destination, except it corresponds to application_data on routepoints. This can either be JSON data or a string. If it is either JSON or a string that can be decoded into JSON (for example, you JSON encode your data before using this endpoint), Summit will attempt to decode the data and pass it to your application as a decoded object instead of a string.
  • external_caller_id_number Optional (string):This parameter specifies the caller ID number which will appear on calls to outside numbers. If included, this number must correspond to a number ordered through Summit. You can view all your numbers from the Summit Platform website or via the REST API. Recommended format is: "15551234567".
  • log_src Optional (string): This lets you specify a value to use for the src and ani attributes on your call records. If you do not include this, we will fall back to the internal_caller_id_number.
  • log_dst Optional (string): This lets you specify the value of the dst and dnis in your call records. If you do not include this, we will fall back to a stringified version of destinations.
  • channel_internal_caller_id_number Optional (string): This works like internal_caller_id_number, except this is the value that appears to the summit app (and anyone dialed by that app).
  • channel_internal_caller_id_name Optional (string): This works like internal_caller_id_name, except this is the value that appears to the summit app (and anyone dialed by that app).
  • channel_external_caller_id_number Optional (string): This works like external_caller_id_number, except this is the value that appears to the summit app (and anyone dialed by that app).
  • destination_allow_outbound_route_caller_id Optional (boolean): If this is true, and your initial destination_type is “outbound”, then a caller_id value set on your outbound_route will override whatever you specified in this request.
  • channel_allow_outbound_route_caller_id Optional (boolean): If this is true, and your application dials some outbound number at some point, then a caller_id value set on your outbound_route will override whatever you might have specified in this request.
  • intercom Optional (boolean): If this is true, then it will attempt to intercom (or auto-answer) exactly one destination. Requests specifying more than one destination will be rejected. The default value is false.
  • affinity_channel_id Optional (string): Proactively optimize the voice traffic by sending a channel_id for a different channel currently in progress that this user might be bridged to (resulting from a channel.dial with destinationType=‘channel’).

Simple POST Example

curl -X POST -v --user YOUR_KEY -H "Content-Type: application/json" -d '{"destinations": ["14145554444"], "internal_caller_id_number": "15554447001", "internal_caller_id_name": "Cal Callington", "schedule": "+5 seconds", "application": "Demo Application", "destination_type":"outbound"}' https://api.us1.corvisa.io/call/schedule

When you are prompted for your password, enter YOUR_SECRET to continue.

GET

Headers

Content-Type: application/json

Response

A sample response will look like:

meta: {
    sort: "scheduled_call.scheduled_call_id",
    start: 0,
    total: 110,
    limit: 25,
    dir: "asc"
},
data: [
    {
        application_data: "{\"state\": \"wisconsin\"}",
        application_destination: "4145551234",
        application_name: "test_summit_app",
        call: [
            {
                accesstier_id: null,
                ani: "5551234567",
                answered_timestamp: "2015-05-01 14:09:24.118352-05:00",
                call_id: "404ed1a7-6817-499e-8216-44218d7b1468",
                connected_duration: 14.469993,
                created_timestamp: "2015-05-01 14:09:14.053377-05:00",
                direction: "outbound",
                dnis: "[3002]"
                domain_id: "65757c51-a53d-4f57-acbc-458cef162706",
                dst: "[3002]",
                ended_timestamp: "2015-05-01 14:09:38.588345-05:00",
                hangup_cause: "7100",
                item_resource_uri: "/latest/call/404ed1a7-6817-499e-8216-44218d7b1468",
                modified_timestamp: "2015-05-01 14:09:38.644428-05:00",
                src: "5551234567",
                started_timestamp: null,
                total_duration: null,
                type_resource_uri: "/latest/call",
            }
        ],
        call_id: "404ed1a7-6817-499e-8216-44218d7b1468",
        canceled_timestamp: "2015-05-01 14:09:38.496751-05:00",
        channel_allow_outbound_route_caller_id: true,
        channel_external_caller_id_number: null,
        channel_internal_caller_id_name: null,
        channel_internal_caller_id_number: null,
        created_timestamp: "2015-05-01 14:09:14.053377-05:00",
        destination_allow_outbound_route_caller_id: true,
        destination_timeout: null,
        destination_type: "endpoint",
        destinations: [
            "3002"
        ],
        domain_id: "65757c51-a53d-4f57-acbc-458cef162706",
        external_caller_id_number: "5555551234",
        internal_caller_id_name: "whatever",
        internal_caller_id_number: "5551234567",
        item_resource_uri: "/v0.0.1/call/schedule/e0af5ec0-1ced-419b-9732-9fd29720de6b",
        log_direction: "outbound",
        modified_timestamp: "2015-05-01 14:09:38.496751-05:00",
        outbound_channel_id: "e0af5ec0-1ced-419b-9732-9fd29720de6b",
        record: null,
        schedule: "2015-05-01 19:09:19.053377-05:00",
        scheduled_call_id: "e0af5ec0-1ced-419b-9732-9fd29720de6b",
        type_resource_uri: "/v0.0.1/call/schedule"
    },
    ...
]

Fields

  • application_data : The data passed as data to the called Application.
  • application_destination : The data passed as destination to the called Application.
  • application_name : The Summit Application which will run. “dial” is the default.
  • call : A reference to the object which represents or will represent your call.
  • call_id : The call_id for this call, when it occurs.
  • canceled_timestamp : If this call was canceled, this will be the time when the request to cancel was received. Otherwise, it will be null.
  • channel_allow_outbound_route_caller_id : Indicates if any outbound dials from the summit app will use the caller_id value on the outbound_route.
  • channel_external_caller_id_number : Indicates the caller_id number seen and passed on externally by the summit app.
  • channel_internal_caller_id_name : Indicates the caller_id name seen and passed on internally by the summit app.
  • channel_internal_caller_id_number : Indicates the caller_id number seen and passed on internally by the summit app.
  • created_timestamp : The time that this object was created.
  • destination_allow_outbound_route_caller_id : If this is true, if the initial dial is to an outbound destination, we will use any caller_id set on your outbound_route regardless of whatever else is in the request.
  • destination_timeout : The ring timeout (in seconds) for the initial call to your specified destination (or 30 if none specified).
  • destination_type : The type of destination (either “outbound” or “endpoint”).
  • destinations : A list of number(s) to call first. If you include multiple, as soon as one number answers, the rest will be disconnected and stop ringing.
  • domain_id : The user’s domain UUID.
  • external_caller_id_number : If the initial call is to an outbound destination, this is the caller_id that will be used (unless other settings override it).
  • internal_caller_id_name : The Caller ID name to display.
  • internal_caller_id_number : The Caller ID number to display.
  • item_resource_uri : The URI for this specific object.
  • modified_timestamp : The last time this object was modified.
  • outbound_channel_id : This is a mirror of the unique ID for this object, the scheduled_call_id. It will eventually be deprecated and removed.
  • record : Whether or not the call should be recorded.
  • schedule : The scheduled time from the initial request.
  • scheduled_call_id : The unique ID for this object.
  • type_resource_uri : The URI for this type of object.

Call Fields

  • accesstier_id : Reserved for future use.
  • ani : The number listed as the source (generally the internal or external caller_id_number).
  • answered_timestamp : The time when the call was answered.
  • call_id : Primary key for the call. This will match the call_id on the scheduled_call object.
  • connected_duration : Total duration for which the call was connected.
  • created_timestamp : The time that this object was created.
  • direction : Direction of the call. Should always be outbound here.
  • dnis : The original DNIS for the call.
  • domain_id : The user’s domain UUID.
  • dst : The original call destination.
  • ended_timestamp : The time when the call ended.
  • hangup_cause : The reason for the hangup.
  • item_resource_uri : The URI for this specific object.
  • modified_timestamp : The last time this object was modified.
  • src : The source number (generally matches the ani).
  • started_timestamp : Initially this should be ignored, but it will eventually contain information about when the call started.
  • total_duration : Total call duration, including time before the destination answered the call.
  • type_resource_uri : The URI for this type of object.

Query Parameters

The control options for all queries from the REST API are:

  • start integer : The starting object.
  • limit integer : The number of objects to display.
  • sort string : The field to sort on. Must correspond to one of the fields listed below.
  • dir “asc”|“desc” : The order of the sort. Must be either “asc” or “desc”.

The following parameters can be passed as query parameters to narrow down your request:

  • application_data : string
  • application_destination : string
  • application_name : string
  • destination_type : “outbound”|“endpoint”
  • destinations : string : Since this field is a list, it has a special syntax: ?destinations={3001,3002} for example, if you specified two. If you just specified one, it would be ?destinations={3001}. Note that order is important: {3002,3001} != {3001,3002}.
  • external_caller_id_number : string
  • internal_caller_id_name : string
  • internal_caller_id_number : string
  • scheduled_channel_id : UUID
  • schedule : timestamp

Cancelling Scheduled Calls

You can also cancel scheduled calls, as long as you do so before they begin. We will keep a record of the Scheduled call (see above for how to view this data) but will mark it as canceled, indicating it will not be placed.

You can only cancel calls before they are placed. If a call has already been canceled, this will return an error. If a call is in progress, this will not force a hangup. Otherwise, this will prevent the call from ever being placed.

Endpoint URL

https://api.us1.corvisa.io/call/schedule/<:id>/cancel

Replace the <:id> parameter with the scheduled_call_id for the call you want to cancel.

Only POST is allowed to this endpoint.

POST

Headers

Content-Type: application/json

Content Body

No body is required for this request.

Simple POST Example

curl -X POST --user YOUR_KEY -H "Content-Type: application/json" https://api.us1.corvisa.io/call/schedule/e0af5ec0-1ced-419b-9732-9fd29720de6b/cancel

When you are prompted for your password, enter YOUR_SECRET to continue.

Response

There are two options for the response, based on whether the request succeeds. On a successful request, we will return the following:

{
    "success": true
}

If there is a problem (for example, the call has already been canceled), we will return the following:

{
    "errorMessage": ERROR_MESSAGE,
    "error": true
}

where ERROR_MESSAGE is some string describing the error (for example, "This call is already canceled").