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.

List all click-to-call endpoints
Create a click-to-call endpoint
Get click-to-call
Change a click-to-call
Patch a click-to-call
Remove a click-to-call
Get click-to-call history
Execute the click-to-call with a supplied number
Change the click-to-call connection

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

List 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