Click-to-Call API

Use the click-to-call API to create URLs that you can post to (either with a phone number or SIP URI), and create a phone call by providing contact information and a predefined destination.

API calls

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

Parameters

The table shows the possible parameters available for click-to-call requests.

Key Description Type Options/Min/Max/Default
extension Required. The extension to connect to when the click to call is invoked. string
name Required. A friendly name for the click to call. string (1..128)
auth_required Determines if this click-to-call requires valid auth-tokens when invoked. boolean The default is true.
bypass_media Default bypass media mode. boolean
caller_id_number The explicitly set caller ID number. string
custom_application_vars./[a-zA-Z0-9\-_]+/ string
custom_application_vars Key-value pairs to set as `custom_application_vars. on the channel object
custom_sip_headers.in Custom SIP Headers to be applied to calls inbound to IP Telecom API from the endpoint. #/definitions/custom_sip_headers
custom_sip_headers.out Custom SIP Headers to be applied to calls outbound from IP Telecom API to the endpoint. #/definitions/custom_sip_headers
custom_sip_headers.^[a-zA-z0-9_\-]+$ The SIP header to add. string
custom_sip_headers A property list of SIP headers. object
dial_first Determines if the extension or contact is dialed first. string extension, contact
media.ignore_early_media The option to determine if early media from the endpoint should always be ignored. boolean()
media The media to use. object
music_on_hold.media_id The ID of a media object that should be used as the music on hold. string (0..2048)
music_on_hold The music on hold parameters used if not a property of the device owner. object
outbound_callee_id_name The callee ID name of the device calling out to the contact number. string()
outbound_callee_id_number The callee ID number of the device calling out to the contact number. string()
presence_id A static presence ID (used instead of SIP username). string
ringback The ringback to use. string
throttle The rate that this click-to-call can be invoked. integer
timeout Specifies, how many seconds the system should wait for the call to progress. integer
whitelist.[] Specific whitelist numbers. string (1..)
whitelist A list of regular expressions that the click-to-call is allowed to dial to. array (string(1..)

Custom SIP headers

Custom SIP headers are applied to an INVITE.

Key Description Type
^[a-zA-z0-9_\-]+$. The SIP header to add string

Get all click-to-call endpoints

Returns a list of all click-to-call endpoints.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/clicktocall

Request

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

Response

  {
      "auth_token":"{AUTH_TOKEN}",
      "data": [
          {
              "extension": "{EXTENSION}",
              "id": "{C2C_ID}",
              "name": "{NAME}"
          }
      ],
      "node": "{NODE_HASH}",
      "page_size": 1,
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success",
      "timestamp": "{TIMESTAMP}",
      "version": "4.3.1"
  }

Create a click-to-call endpoint

Creates a click-to-call endpoint.

Method and endpoint

  PUT /v2/accounts/{ACCOUNT_ID}/clicktocall

Request

  curl -v -X PUT \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      -d '{"data":{"name":"{NAME}, "auth_required":false, "extension":"{EXTENSION}"}}'
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/clicktocall

Response

  {
      "auth_token":"{AUTH_TOKEN}",
      "data": {
          "auth_required": false,
          "custom_application_vars": {},
          "extension": "{EXTENSION}",
          "id": "{C2C_ID}",
          "name": "{NAME}"
      },
      "node": "{NODE_HASH}",
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success",
      "timestamp": "{TIMESTAMP}",
      "version": "4.3.1"
  }

Get click-to-call

Returns details of a specific click-to-call event.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}

Request

  curl -v -X GET \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}

Response

  {
      "auth_token":"{AUTH_TOKEN}",
      "data": {
          "auth_required": false,
          "custom_application_vars": {},
          "extension": "{EXTENSION}",
          "id": "{C2C_ID}",
          "name": "{NAME}"
      },
      "node": "{NODE_HASH}",
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success",
      "timestamp": "{TIMESTAMP}",
      "version": "4.3.1"
  }

Change a click-to-call

Updates a click-to-call.

Method and endpoint

  POST /v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}

Request

  curl -v -X POST \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}

Patch a click-to-call

Partially updates a click-to-call.

Method and endpoint

  PATCH /v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}

Request

  curl -v -X PATCH \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}

Remove a click-to-call

Removes a click-to-call.

Method and endpoint

  DELETE /v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}

Request

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}

Get click-to-call history

Returns all the click-to-call history.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}/history

Request

  curl -v -X GET \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}/history

Execute the click-to-call with a supplied number

Executes the click-to-call.

Method and endpoint

  GET/POST /v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}/connect

Request

  curl -v -X GET \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}/connect?contact={CONTACT}

NOTE: The non-blocking version returns immediately with a 202

      "data": {
          "application_data": {
              "route": "{CONTACT}"
          },
          "application_name": "transfer",
          "continue_on_fail": true,
          "custom_application_vars": {
              "contact": "{CONTACT}"
          },
          "custom_channel_vars": {
              "account_id": "{ACCOUNT_ID}",
              "authorizing_id": "{C2C_ID}",
              "authorizing_type": "clicktocall",
              "auto_answer_loopback": true,
              "from_uri": "{EXTENSION}@{ACCOUNT_REALM}",
              "inherit_codec": false,
              "loopback_request_uri": "{CONTACT}@{ACCOUNT_REALM}",
              "request_uri": "{CONTACT}@{ACCOUNT_REALM}",
              "retain_cid": true
          },
          "dial_endpoint_method": "single",
          "endpoints": [
              {
                  "invite_format": "loopback",
                  "route": "{EXTENSION}",
                  "to_did": "{EXTENSION}",
                  "to_realm": "{ACCOUNT_REALM}"
              }
          ],
          "export_custom_channel_vars": [
              "Account-ID",
              "Authorizing-ID",
              "Authorizing-Type",
              "Loopback-Request-URI",
              "From-URI",
              "Request-URI"
          ],
          "ignore_early_media": true,
          "loopback_bowout": "false",
          "outbound_call_id": "c2c-{C2C_ID}-{RANDOM}",
          "outbound_callee_id_name": "{EXTENSION}",
          "outbound_callee_id_number": "{EXTENSION}",
          "outbound_caller_id_name": "{C2C NAME}",
          "outbound_caller_id_number": "{CONTACT}",
          "simplify_loopback": "false",
          "start_control_process": "false",
          "timeout": 30
      },
      "node": "{NODE_HASH}",
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success",
      "timestamp": "{TIMESTAMP}",
      "version": "4.3.1"
  }

Change the click-to-call connection

Updates the click-to-call connection details.

Method and endpoint

  POST /v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}/connect

Request

  curl -v -X POST \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/clicktocall/{C2C_ID}/connect