From b56c634d7732f69520ace5e6cbb0048f10e25791 Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Wed, 21 Oct 2026 16:41:22 +0100 Subject: [PATCH 1/4] Document the contact identifiers accepted when creating a conversation Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 14 +++++++++++--- descriptions/2.17/api.intercom.io.yaml | 14 +++++++++++--- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index be7b0b4c..7bd84d61 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -13358,7 +13358,7 @@ paths: The conversation can be an in-app message only. {% admonition type="info" name="Sending for visitors" %} - You can also send a message from a visitor by specifying their `user_id` or `id` value in the `from` field, along with a `type` field value of `contact`. + You can also send a message from a visitor by specifying their `id` value in the `from` field, along with a `type` field value of `lead`. This visitor will be automatically converted to a contact with a lead role once the conversation is created. {% /admonition %} @@ -37320,19 +37320,27 @@ components: enum: - lead - user - - contact description: The role associated to the contact - user or lead. example: user id: type: string description: The identifier for the contact which is given by Intercom. + Provide one of `id`, `user_id` or `email`. format: uuid minLength: 24 maxLength: 24 example: 536e564f316c83104c000020 + user_id: + type: string + description: The external identifier you gave the contact. Provide one of + `id`, `user_id` or `email`. + example: '25' + email: + type: string + description: The contact's email. Provide one of `id`, `user_id` or `email`. + example: joe@example.com required: - type - - id body: type: string description: The content of the message. HTML is not supported. diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index dce133b3..9bf265ba 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -13512,7 +13512,7 @@ paths: The conversation can be an in-app message only. {% admonition type="info" name="Sending for visitors" %} - You can also send a message from a visitor by specifying their `user_id` or `id` value in the `from` field, along with a `type` field value of `contact`. + You can also send a message from a visitor by specifying their `id` value in the `from` field, along with a `type` field value of `lead`. This visitor will be automatically converted to a contact with a lead role once the conversation is created. {% /admonition %} @@ -32815,19 +32815,27 @@ components: enum: - lead - user - - contact description: The role associated to the contact - user or lead. example: user id: type: string description: The identifier for the contact which is given by Intercom. + Provide one of `id`, `user_id` or `email`. format: uuid minLength: 24 maxLength: 24 example: 536e564f316c83104c000020 + user_id: + type: string + description: The external identifier you gave the contact. Provide one of + `id`, `user_id` or `email`. + example: '25' + email: + type: string + description: The contact's email. Provide one of `id`, `user_id` or `email`. + example: joe@example.com required: - type - - id body: type: string description: The content of the message. HTML is not supported. From fdd1c6e9b0b260ab59f630a894c6e07f8e9b6da6 Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Wed, 21 Oct 2026 17:41:52 +0100 Subject: [PATCH 2/4] Clarify which contact identifiers match users and leads Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 9 +++++---- descriptions/2.17/api.intercom.io.yaml | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 7bd84d61..02285b64 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -37326,18 +37326,19 @@ components: type: string description: The identifier for the contact which is given by Intercom. Provide one of `id`, `user_id` or `email`. - format: uuid minLength: 24 maxLength: 24 example: 536e564f316c83104c000020 user_id: type: string - description: The external identifier you gave the contact. Provide one of - `id`, `user_id` or `email`. + description: The external identifier you gave the user. Matches users only; + for a lead, use `id` or `email`. example: '25' email: type: string - description: The contact's email. Provide one of `id`, `user_id` or `email`. + description: The contact's email. Matches a user or a lead, depending on + `type`. If several leads share the email, the request fails with `multiple_users`; + use `id` instead. example: joe@example.com required: - type diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 9bf265ba..4c60a29a 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -32821,18 +32821,19 @@ components: type: string description: The identifier for the contact which is given by Intercom. Provide one of `id`, `user_id` or `email`. - format: uuid minLength: 24 maxLength: 24 example: 536e564f316c83104c000020 user_id: type: string - description: The external identifier you gave the contact. Provide one of - `id`, `user_id` or `email`. + description: The external identifier you gave the user. Matches users only; + for a lead, use `id` or `email`. example: '25' email: type: string - description: The contact's email. Provide one of `id`, `user_id` or `email`. + description: The contact's email. Matches a user or a lead, depending on + `type`. If several leads share the email, the request fails with `multiple_users`; + use `id` instead. example: joe@example.com required: - type From b4bf47125d3d6ad7535529cfab149c12bb20603d Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Wed, 21 Oct 2026 18:33:00 +0100 Subject: [PATCH 3/4] Say which contact identifier is used when more than one is sent Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 8 +++++--- descriptions/2.17/api.intercom.io.yaml | 8 +++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 02285b64..92ed9ce3 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -37325,7 +37325,8 @@ components: id: type: string description: The identifier for the contact which is given by Intercom. - Provide one of `id`, `user_id` or `email`. + Provide one of `id`, `user_id` or `email`. If you send more than one, + `id` is used first, then `user_id`. minLength: 24 maxLength: 24 example: 536e564f316c83104c000020 @@ -37337,8 +37338,9 @@ components: email: type: string description: The contact's email. Matches a user or a lead, depending on - `type`. If several leads share the email, the request fails with `multiple_users`; - use `id` instead. + `type`. Used only when `user_id` isn't sent. If several leads share the + email and it's the only identifier sent, the request fails with + `multiple_users`; use `id` instead. example: joe@example.com required: - type diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 4c60a29a..d5494af3 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -32820,7 +32820,8 @@ components: id: type: string description: The identifier for the contact which is given by Intercom. - Provide one of `id`, `user_id` or `email`. + Provide one of `id`, `user_id` or `email`. If you send more than one, + `id` is used first, then `user_id`. minLength: 24 maxLength: 24 example: 536e564f316c83104c000020 @@ -32832,8 +32833,9 @@ components: email: type: string description: The contact's email. Matches a user or a lead, depending on - `type`. If several leads share the email, the request fails with `multiple_users`; - use `id` instead. + `type`. Used only when `user_id` isn't sent. If several leads share the + email and it's the only identifier sent, the request fails with + `multiple_users`; use `id` instead. example: joe@example.com required: - type From 575f5d97023d5fbf851b5d2427eb72f28067815c Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Thu, 22 Oct 2026 08:40:01 +0100 Subject: [PATCH 4/4] Keep contact as an accepted from type Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 3 ++- descriptions/2.17/api.intercom.io.yaml | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 92ed9ce3..049a96c9 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -13358,7 +13358,7 @@ paths: The conversation can be an in-app message only. {% admonition type="info" name="Sending for visitors" %} - You can also send a message from a visitor by specifying their `id` value in the `from` field, along with a `type` field value of `lead`. + You can also send a message from a visitor by specifying their `user_id` or `id` value in the `from` field, along with a `type` field value of `contact`. This visitor will be automatically converted to a contact with a lead role once the conversation is created. {% /admonition %} @@ -37320,6 +37320,7 @@ components: enum: - lead - user + - contact description: The role associated to the contact - user or lead. example: user id: diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index d5494af3..1a55a6d7 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -13512,7 +13512,7 @@ paths: The conversation can be an in-app message only. {% admonition type="info" name="Sending for visitors" %} - You can also send a message from a visitor by specifying their `id` value in the `from` field, along with a `type` field value of `lead`. + You can also send a message from a visitor by specifying their `user_id` or `id` value in the `from` field, along with a `type` field value of `contact`. This visitor will be automatically converted to a contact with a lead role once the conversation is created. {% /admonition %} @@ -32815,6 +32815,7 @@ components: enum: - lead - user + - contact description: The role associated to the contact - user or lead. example: user id: