Intercom API (unofficial showcase)
POST/conversations/{conversation_id}/customers

Attach a contact to a conversation

Adds a contact as a participant in a conversation on behalf of an admin or another contact. Identify the contact using an Intercom user ID, a user ID, or an email address in customer. If no contact exists for a supplied email address, the API creates a contact with the lead role.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 2 body fields
conversation_idstringrequired
The identifier of the conversation to add a participant to.
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Optional participant details identifying the admin performing the action and the contact to add.

admin_idstringoptional
The `id` of the admin who is adding the new participant.
customerobjectoptional
The contact to add, identified by an Intercom user ID, user ID, or email address.

4 status codes
200Returns the conversation's participants after the contact is attached.
customersarray<object>required
The conversation participants after the change
401Returned when the request is not authenticated.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
403Returned when the API plan restricts attaching contacts.

One documented failure

  • api_plan_restricted

    Active subscription needed.

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
404Returned when the conversation or contact cannot be found.

One documented failure

  • not_found

    Resource Not Found

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when authentication is missing or invalid; a 403 when the API plan restricts the operation; and a 404 when the conversation or contact cannot be found. The conversation_id path parameter must identify a conversation. When supplying customer, identify the contact with intercom_user_id, user_id, or email.