Quickcall API

Use the quickcall API to manage legs between endpoints such as users and devices.

API calls

Click on each call to view the endpoint, method, and request example.

• Non-blocking quickcall
• Blocking quickcall
• Execute a quick call for a device
• Execute a quick call for a user
• Failing requests

Parameters

The table shows the possible parameters available for quickcall requests.

Field	Description	Type	Options/Min/Max/Default
auto_answer	If this parameter is supported, it tells the SIP phone to auto-answer the call.	boolean
cid-name	The caller ID name.	string	The default is Device QuickCall.
cid-number	The caller ID number.	string	The default is the {PHONE_NUMBER}.
custom_application_vars	Defines custom data to include on the call and on events related to the call.	object
ignore-early-media	Specifies whether to ignore early media.	boolean
media	Specifies whether to go peer-to-peer (bypass with the RTP).	string	(bypass, process)
number_filter	If set to true, this paramter removes non-alphanumeric characters. If it is a regex, use the first capture group as the "number" to dial.	boolean , regex
target_call_id	An existing call-id that is used to determine which media server the quickcall leg should be created on.	string
timeout	Defines how many seconds the device should ring for.	integer	(3..) The default is 30 seconds.

NOTES:

Target call ID

If you know ahead of time that this new quickcall leg will be interacting with an existing call leg, then supply the existing call-id to the API call to ensure that the new leg is created on the same media server as the existing call leg.

Custom application vars

Custom application vars (CAVs) enable you to set custom data to appear on subsequent call events (found in Webhook and Websocket payloads) as well as the final CDR.

There are two ways to specify CAVs:

1. As query-string parameters: /quickcall/{NUMBER}?foo=bar.
2. As a POST body: {"data":{"custom_application_vars":{"foo":"bar"}}}

Supported endpoints for quickcalls

Endpoint Type	Endpoint Id
users	{USER_ID}
devices	{DEVICE_ID}

Non-blocking quickcall

Returns a 202 accepted status code immediately.

NOTE: If no endpoints are found to originate to, then there are no channel events generated to inform the external application if the quickcall failed.

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/{ENDPOINTS}/{ENDPOINT_ID}/quickcall/{NUMBER}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/{ENDPOINTS}/{ENDPOINT_ID}/quickcall/{NUMBER}

Blocking quickcall

Returns a 202 if the quickcall successfully originates (meaning a channel is started). It returns errors if the originate request fails to start a channel or if there aren't any endpoints available.

Method and endpoint

POST /v2/accounts/{ACCOUNT_ID}/{ENDPOINTS}/{ENDPOINT_ID}/quickcall/{NUMBER}

Request

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/{ENDPOINTS}/{ENDPOINT_ID}/quickcall/{NUMBER}

Execute a quick call for a device

Rings the device, and after it is answered, connects it to {PHONE_NUMBER}.

NOTE: In this scenario, the device is considered the callee while the {PHONE_NUMBER} side is considered the caller.

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/quickcall/{PHONE_NUMBER}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/quickcall/{PHONE_NUMBER}

Response

  {
    "auth_token": "{AUTH_TOKEN}",
    "data": {
      "export_custom_channel_vars": [
        "Account-ID",
        "Retain-CID",
        "Authorizing-ID",
        "Authorizing-Type"
      ],
      "custom_channel_vars": {
        "authorizing_id": "{DEVICE_ID}",
        "authorizing_type": "device",
        "inherit_codec": "false",
        "retain_cid": "true",
        "account_id": "{ACCOUNT_ID}"
      },
      "continue_on_fail": false,
      "dial_endpoint_method": "simultaneous",
      "outbound_callee_id_number": "{DEVICE_CALLER_ID_NUMBER}",
      "outbound_callee_id_name": "{DEVICE_CALLER_ID_NAME}",
      "outbound_caller_id_number": "{E164_NUMBER}",
      "outbound_caller_id_name": "Device QuickCall",
      "media": "process",
      "ignore_early_media": true,
      "timeout": 30,
      "endpoints": [
        {
          "outbound_call_id": "{CALL_ID}-quickcall",
          "custom_channel_vars": {
            "auto_answer": true,
            "authorizing_id": "{DEVICE_ID}",
            "owner_id": "{USER_ID}",
            "account_id": "{ACCOUNT_ID}",
            "media_encryption_enforce_security": false,
            "sip_invite_domain": "{ACCOUNT_REALM}"
          },
          "custom_sip_headers": {
            "x_kazoo_aor": "sip:{DEVICE_SIP_USER}@{ACCOUNT_REALM}"
          },
          "presence_id": "{PRESENCE_ID}",
          "codecs": [
            "PCMU",
            "PCMA"
          ],
          "endpoint_id": "{DEVICE_ID}",
          "to_did": "{E164_NUMBER}",
          "to_realm": "{ACCOUNT_REALM}",
          "to_username": "{DEVICE_SIP_USER}",
          "to_user": "{DEVICE_SIP_USER}",
          "invite_format": "username"
        }
      ],
      "application_data": {
        "route": "{PHONE_NUMBER}"
      },
      "application_name": "transfer"
    },
    "status": "success",
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}"
  }

Execute a quick call for a user

Rings the user's device, and after it is answered, connects to {PHONE_NUMBER}.

NOTE: In this scenario, the user's devices are considered the callee while the {PHONE_NUMBER} side is considered the caller.

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/quickcall/{PHONE_NUMBER}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/quickcall/{PHONE_NUMBER}

Response

  {
    "auth_token": "{AUTH_TOKEN}",
    "data": {
      "export_custom_channel_vars": [
        "Account-ID",
        "Retain-CID",
        "Authorizing-ID",
        "Authorizing-Type"
      ],
      "custom_channel_vars": {
        "authorizing_id": "{USER_ID}",
        "authorizing_type": "user",
        "inherit_codec": "false",
        "retain_cid": "true",
        "account_id": "{ACCOUNT_ID}"
      },
      "continue_on_fail": false,
      "dial_endpoint_method": "simultaneous",
      "outbound_callee_id_number": "{DEVICE_CALLER_ID_NUMBER}",
      "outbound_callee_id_name": "{DEVICE_CALLER_ID_NAME}",
      "outbound_caller_id_number": "{E164_NUMBER}",
      "outbound_caller_id_name": "Device QuickCall",
      "media": "process",
      "ignore_early_media": true,
      "timeout": 30,
      "endpoints": [
        {
          "outbound_call_id": "{CALL_ID}-quickcall",
          "custom_channel_vars": {
            "auto_answer": true,
            "authorizing_id": "{USER_ID}",
            "owner_id": "{USER_ID}",
            "account_id": "{ACCOUNT_ID}",
            "media_encryption_enforce_security": false,
            "sip_invite_domain": "{ACCOUNT_REALM}"
          },
          "custom_sip_headers": {
            "x_kazoo_aor": "sip:{DEVICE_SIP_USER}@{ACCOUNT_REALM}"
          },
          "presence_id": "{PRESENCE_ID}",
          "codecs": [
            "PCMU",
            "PCMA"
          ],
          "endpoint_id": "{DEVICE_ID}",
          "to_did": "{E164_NUMBER}",
          "to_realm": "{ACCOUNT_REALM}",
          "to_username": "{DEVICE_SIP_USER}",
          "to_user": "{DEVICE_SIP_USER}",
          "invite_format": "username"
        }
      ],
      "application_data": {
        "route": "{PHONE_NUMBER}"
      },
      "application_name": "transfer"
    },
    "status": "success",
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}"
  }

Failing requests

If Quickcall is issued with a GET to an unregistered device (or a user with no available devices), it returns the call setup information immediately but no channel events are generated (no events for webhooks/websockets). External apps do not know if the quickcall was originated properly or not.

Therefore, it is advisable to use POST which blocks the API request until the channel starts or the quickcall fails. An example of a failing quickcall (which generated no call events):

Failed quickcall response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "error_message": "DESTINATION_OUT_OF_ORDER",
        "request": {
            "app_name": "crossbar",
            "app_version": "4.0.0",
            "application_data": {
                "route": "{EXTENSION}"
            },
            "application_name": "transfer",
            "continue_on_fail": false,
            "custom_channel_vars": {
                "account_id": "{ACCOUNT_ID}",
                "authorizing_id": "{DEVICE_ID}",
                "authorizing_type": "device",
                "inherit_codec": "false",
                "retain_cid": "true"
            },
            "dial_endpoint_method": "simultaneous",
            "endpoints": [
                {
                    "codecs": [
                        "PCMU",
                        "PCMA"
                    ],
                    "custom_channel_vars": {
                        "account_id": "{ACCOUNT_ID}",
                        "authorizing_id": "{DEVICE_ID}",
                        "authorizing_type": "device",
                        "auto_answer": true,
                        "media_encryption_enforce_security": false,
                        "sip_invite_domain": "{SIP_REALM}"
                    },
                    "custom_sip_headers": {
                        "x_kazoo_aor": "sip:{SIP_USERNAME}@{SIP_REALM}",
                        "x_kazoo_invite_format": "contact"
                    },
                    "ignore_completed_elsewhere": false,
                    "invite_format": "contact",
                    "outbound_call_id": "{CALL_ID}-quickcall",
                    "presence_id": "{SIP_USERNAME}@{SIP_REALM}",
                    "to_did": "{EXTENSION}",
                    "to_realm": "{SIP_REALM}",
                    "to_user": "{SIP_USERNAME}",
                    "to_username": "{SIP_USERNAME}"
                }
            ],
            "event_category": "resource",
            "event_name": "originate_req",
            "export_custom_channel_vars": [
                "Account-ID",
                "Retain-CID",
                "Authorizing-ID",
                "Authorizing-Type",
                "Outbound-Callee-ID-Number",
                "Outbound-Callee-ID-Name"
            ],
            "ignore_early_media": true,
            "media": "process",
            "msg_id": "{MSG_ID}",
            "node": "{NODE}",
            "outbound_callee_id_name": "{DEVICE_CALLER_ID_NAME}",
            "outbound_callee_id_number": "{DEVICE_CALLER_ID_NUMBER}",
            "outbound_caller_id_name": "Device QuickCall",
            "outbound_caller_id_number": "{EXTENSION}",
            "server_id": "{API_AMQP_QUEUE}",
            "system_log_id": "{LOG_ID}",
            "timeout": 30
        }
    },
    "error": "500",
    "message": "quickcall initiation failed",
    "node": "{NODE}",
    "request_id": "{REQUEST_ID}",
    "status": "error",
    "timestamp": "{TIMESTAMP}",
    "version": "4.2.2"
}