Skip to content
Home/
/Switch

Create a phone Switch

Request

You can use the API to deflect phone calls to the Intercom Messenger. Calling this endpoint will send an SMS with a link to the Messenger to the phone number specified.

If custom attributes are specified, they will be added to the user or lead's custom data attributes.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.17
Bodyapplication/json
phonestringrequired

Phone number in E.164 format, that will receive the SMS to continue the conversation in the Messenger.

Example:"+1 1234567890"
custom_attributesobject

Custom attributes to add to the user or lead's custom data attributes. Values are strings. Numbers and booleans are converted to strings. An empty string, or any array or object value, returns a 422 error with the key context. A null value is ignored.

Example:
{
  "issue_type": "Billing",
  "priority": "High"
}
bodystring

The text of the contact's first message. When you send it, a conversation is created straight away with this text as its first message.

Example:"I need help with my invoice"
send_notificationboolean

Whether to send the SMS with the link to the Messenger. When false, no SMS is sent.

Default:true
Example:true
user_input_phonestring or null

The phone number as the contact typed it, in national format. When sent with country, used in place of phone to read the number. phone is still required.

Example:"087 234 5678"
countrystring or null

The two-letter country code used to read user_input_phone. When country is US, Intercom also looks up the carrier to detect landlines.

Example:"IE"
curl -i -X POST \
  https://api.intercom.io/phone_call_redirects \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "phone": "+353832345678",
    "custom_attributes": {
      "issue_type": "Billing",
      "priority": "High"
    }
  }'

Responses

successful

Bodyapplication/json
typestring
Default:"phone_call_redirect"
Value:"phone_call_redirect"
Example:"phone_call_redirect"
urlstring

The Messenger link for the phone call redirect, which is also the link sent by SMS to the phone number.

Example:"http://via.intercom.io/msgr/1add3dd1-a75e-4a96-96fd-984d16aba059"
Response
{
  "url": "http://via.intercom.io/msgr/1add3dd1-a75e-4a96-96fd-984d16aba059",
  "type": "phone_call_redirect"
}