Skip to content

Commit 380b41a

Browse files
auroraliminauroralimin
committed
Add Custom Channel Event endpoints documentation
Add documentation for the new API endpoints for Custom Channel Event, that are used on a closed beta to achieve "Fin over API" integrations.
1 parent 9457fde commit 380b41a

File tree

2 files changed

+332
-0
lines changed

2 files changed

+332
-0
lines changed

‎descriptions/0/api.intercom.io.yaml

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7523,6 +7523,206 @@ paths:
75237523
summary: Bad request
75247524
value:
75257525
ticket_type_id: '54'
7526+
"/custom_channel_events/new_conversation":
7527+
post:
7528+
summary: Notify Intercom of a new conversation created in a custom channel
7529+
tags:
7530+
- Custom Channel Events
7531+
operationId: notifyNewConversation
7532+
description: |
7533+
Notifies Intercom that a new conversation was created in your custom channel/platform. This triggers conversation creation and workflow automations within Intercom for your custom channel integration.
7534+
> **Note:** This endpoint is restricted to customers with access to the closed beta for "Fin over API".
7535+
parameters:
7536+
- name: Intercom-Version
7537+
in: header
7538+
required: true
7539+
schema:
7540+
$ref: '#/components/schemas/intercom_version_unstable'
7541+
requestBody:
7542+
required: true
7543+
content:
7544+
application/json:
7545+
schema:
7546+
$ref: '#/components/schemas/custom_channel_base_event'
7547+
examples:
7548+
example-1:
7549+
summary: Example request
7550+
value:
7551+
event_id: "evt_12345"
7552+
conversation_id: "conv_67890"
7553+
contact:
7554+
type: "user"
7555+
external_id: "user_001"
7556+
name: "Jane Doe"
7557+
email: "jane.doe@example.com"
7558+
responses:
7559+
'204':
7560+
description: Successfully notified Intercom of the new conversation.
7561+
'400':
7562+
$ref: '#/components/responses/BadRequest'
7563+
'401':
7564+
$ref: "#/components/responses/Unauthorized"
7565+
'404':
7566+
$ref: '#/components/responses/ObjectNotFound'
7567+
'422':
7568+
$ref: '#/components/responses/ValidationError'
7569+
/custom_channel_events/message:
7570+
post:
7571+
summary: Notify Intercom of a new message in a custom channel conversation
7572+
tags:
7573+
- Custom Channel Events
7574+
operationId: notifyNewMessage
7575+
description: |
7576+
Notifies Intercom that a new message was sent in a conversation on your custom channel/platform. This allows Intercom to process the message and trigger any relevant workflow automations.
7577+
> **Note:** This endpoint is restricted to customers with access to the closed beta for "Fin over API".
7578+
parameters:
7579+
- name: Intercom-Version
7580+
in: header
7581+
required: true
7582+
schema:
7583+
$ref: '#/components/schemas/intercom_version_unstable'
7584+
requestBody:
7585+
required: true
7586+
content:
7587+
application/json:
7588+
schema:
7589+
allOf:
7590+
- $ref: '#/components/schemas/custom_channel_base_event'
7591+
- type: object
7592+
properties:
7593+
body:
7594+
type: string
7595+
description: The message content sent by the user.
7596+
required:
7597+
- body
7598+
examples:
7599+
example-1:
7600+
summary: Example request
7601+
value:
7602+
event_id: "evt_54321"
7603+
conversation_id: "conv_98765"
7604+
contact:
7605+
type: "user"
7606+
external_id: "user_002"
7607+
name: "John Smith"
7608+
email: "john.smith@example.com"
7609+
body: "Hello, I need help with my order."
7610+
responses:
7611+
'204':
7612+
description: Successfully notified Intercom of the new message.
7613+
'400':
7614+
$ref: '#/components/responses/BadRequest'
7615+
'401':
7616+
$ref: "#/components/responses/Unauthorized"
7617+
'404':
7618+
$ref: '#/components/responses/ObjectNotFound'
7619+
'422':
7620+
$ref: '#/components/responses/ValidationError'
7621+
/custom_channel_events/quick_reply_response:
7622+
post:
7623+
summary: Notify Intercom of a quick reply response in a custom channel conversation
7624+
tags:
7625+
- Custom Channel Events
7626+
operationId: notifyQuickReplyResponse
7627+
description: |
7628+
Notifies Intercom that a user selected a quick reply option in your custom channel/platform. This allows Intercom to process the response and trigger any relevant workflow automations.
7629+
> **Note:** This endpoint is restricted to customers with access to the closed beta for "Fin over API".
7630+
parameters:
7631+
- name: Intercom-Version
7632+
in: header
7633+
required: true
7634+
schema:
7635+
$ref: '#/components/schemas/intercom_version_unstable'
7636+
requestBody:
7637+
required: true
7638+
content:
7639+
application/json:
7640+
schema:
7641+
allOf:
7642+
- $ref: '#/components/schemas/custom_channel_base_event'
7643+
- type: object
7644+
properties:
7645+
quick_reply_option_uuid:
7646+
type: string
7647+
description: UUID of the selected quick reply option.
7648+
required:
7649+
- quick_reply_option_uuid
7650+
examples:
7651+
example-1:
7652+
summary: Example request
7653+
value:
7654+
event_id: "evt_67890"
7655+
conversation_id: "conv_13579"
7656+
contact:
7657+
type: "user"
7658+
external_id: "user_003"
7659+
name: "Alice Example"
7660+
email: "alice@example.com"
7661+
quick_reply_option_uuid: "b7e6a2c4-8f3a-4d2e-9c1a-2f6b7e8a9c3d"
7662+
responses:
7663+
'204':
7664+
description: Successfully notified Intercom of the quick reply response.
7665+
'400':
7666+
$ref: '#/components/responses/BadRequest'
7667+
'401':
7668+
$ref: "#/components/responses/Unauthorized"
7669+
'404':
7670+
$ref: '#/components/responses/ObjectNotFound'
7671+
'422':
7672+
$ref: '#/components/responses/ValidationError'
7673+
/custom_channel_events/attribute_collector_response:
7674+
post:
7675+
summary: Notify Intercom of an attribute collector response in a custom channel conversation
7676+
tags:
7677+
- Custom Channel Events
7678+
operationId: notifyAttributeCollectorResponse
7679+
description: |
7680+
Notifies Intercom that a user provided a response to an attribute collector in your custom channel/platform. This allows Intercom to process the attribute and trigger any relevant workflow automations.
7681+
> **Note:** This endpoint is restricted to customers with access to the closed beta for "Fin over API".
7682+
parameters:
7683+
- name: Intercom-Version
7684+
in: header
7685+
required: true
7686+
schema:
7687+
$ref: '#/components/schemas/intercom_version_unstable'
7688+
requestBody:
7689+
required: true
7690+
content:
7691+
application/json:
7692+
schema:
7693+
allOf:
7694+
- $ref: '#/components/schemas/custom_channel_base_event'
7695+
- type: object
7696+
properties:
7697+
attribute:
7698+
$ref: '#/components/schemas/custom_channel_attribute'
7699+
required:
7700+
- attribute
7701+
examples:
7702+
example-1:
7703+
summary: Example request
7704+
value:
7705+
event_id: "evt_24680"
7706+
conversation_id: "conv_11223"
7707+
contact:
7708+
type: "user"
7709+
external_id: "user_004"
7710+
name: "Bob Example"
7711+
email: "bob@example.com"
7712+
attribute:
7713+
id: "shipping_address"
7714+
value: "123 Main St, Springfield"
7715+
responses:
7716+
'204':
7717+
description: Successfully notified Intercom of the attribute collector response.
7718+
'400':
7719+
$ref: '#/components/responses/BadRequest'
7720+
'401':
7721+
$ref: "#/components/responses/Unauthorized"
7722+
'404':
7723+
$ref: '#/components/responses/ObjectNotFound'
7724+
'422':
7725+
$ref: '#/components/responses/ValidationError'
75267726
"/custom_object_instances/{custom_object_type_identifier}":
75277727
parameters:
75287728
- name: custom_object_type_identifier
@@ -17386,6 +17586,58 @@ components:
1738617586
type: string
1738717587
description: Name of the action
1738817588
example: Jira Create Issue
17589+
custom_channel_attribute:
17590+
title: Custom Channel - Attribute
17591+
type: object
17592+
required:
17593+
- id
17594+
- value
17595+
properties:
17596+
id:
17597+
type: string
17598+
description: Identifier for the attribute being collected.
17599+
value:
17600+
type: string
17601+
description: Value provided by the user for the attribute.
17602+
custom_channel_base_event:
17603+
title: Custom Channel - Base Event
17604+
type: object
17605+
properties:
17606+
event_id:
17607+
type: string
17608+
description: Unique identifier for the event.
17609+
conversation_id:
17610+
type: string
17611+
description: Identifier for the conversation in your system.
17612+
contact:
17613+
$ref: '#/components/schemas/custom_channel_contact'
17614+
required:
17615+
- event_id
17616+
- conversation_id
17617+
- contact
17618+
custom_channel_contact:
17619+
title: Custom Channel - Simplified Contact
17620+
type: object
17621+
required:
17622+
- type
17623+
- external_id
17624+
- name
17625+
- email
17626+
properties:
17627+
type:
17628+
type: string
17629+
enum: [user, lead]
17630+
description: Type of contact, must be "user" or "lead".
17631+
external_id:
17632+
type: string
17633+
description: External identifier for the contact. Intercom will take care of the mapping of your external_id with our internal ones so you don't have to worry about it.
17634+
name:
17635+
type: string
17636+
description: Name of the contact.
17637+
email:
17638+
type: string
17639+
format: email
17640+
description: Email address of the contact.
1738917641
custom_action_finished:
1739017642
title: Part type - custom_action_finished
1739117643
type: object
@@ -17934,6 +18186,13 @@ components:
1793418186
-
1793518187
example: Customer
1793618188
nullable: true
18189+
intercom_version_unstable:
18190+
description: Unstable Intercom API version. Used for closed beta endpoints.
18191+
type: string
18192+
example: unstable
18193+
default: unstable
18194+
enum:
18195+
- unstable
1793718196
linked_object_list:
1793818197
title: Linked Objects
1793918198
type: object
@@ -20383,12 +20642,54 @@ components:
2038320642
application/json:
2038420643
examples:
2038520644
ObjectNotFound:
20645+
value:
20646+
type: error.list
20647+
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
20648+
errors:
20649+
- code: not_found
20650+
message: Object not found
20651+
CustomObjectNotFound:
2038620652
value:
2038720653
type: error.list
2038820654
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
2038920655
errors:
2039020656
- code: not_found
2039120657
message: Custom object instance not found
20658+
IntegrationNotFound:
20659+
value:
20660+
type: error.list
20661+
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
20662+
errors:
20663+
- code: data_invalid
20664+
message: Integration not found
20665+
schema:
20666+
"$ref": "#/components/schemas/error"
20667+
ValidationError:
20668+
description: Validation Error
20669+
content:
20670+
application/json:
20671+
examples:
20672+
ValidationError:
20673+
value:
20674+
type: error.list
20675+
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
20676+
errors:
20677+
- code: data_invalid
20678+
message: Invalid or duplicated record reference
20679+
schema:
20680+
"$ref": "#/components/schemas/error"
20681+
BadRequest:
20682+
description: Bad Request
20683+
content:
20684+
application/json:
20685+
examples:
20686+
BadRequest:
20687+
value:
20688+
type: error.list
20689+
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
20690+
errors:
20691+
- code: data_invalid
20692+
message: Contact not found or could not be created
2039220693
schema:
2039320694
"$ref": "#/components/schemas/error"
2039420695
servers:
@@ -20431,6 +20732,13 @@ tags:
2043120732
externalDocs:
2043220733
description: What is a conversation?
2043320734
url: https://www.intercom.com/help/en/articles/4323904-what-is-a-conversation
20735+
- name: Custom Channel Events
20736+
description: |
20737+
With the **closed beta** "Custom Channel" integration, you can bring Fin and Intercom capabilities to your own platform via API, enabling powerful custom integrations.
20738+
20739+
Intercom treats your integration like any other Intercom channel, allowing your application and Intercom to exchange events seamlessly. This makes it possible, for example, for your users to interact with Fin directly within your own application’s UI.
20740+
20741+
> **Note:** If you are interested in joining our closed beta and have a use case to integrate with "Fin over API", please reach out to your account manager or our support team for further information.
2043420742
- name: Custom Object Instances
2043520743
description: |
2043620744
Everything about your Custom Object instances.

‎fern/openapi-overrides.yml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -442,6 +442,30 @@ paths:
442442
- conversations
443443
x-fern-sdk-method-name: redactConversationPart
444444
x-fern-request-name: RedactConversationPartRequest
445+
/custom_channel_events/attribute_collector_response:
446+
post:
447+
x-fern-sdk-group-name:
448+
- customChannelEvents
449+
x-fern-sdk-method-name: createAttributeCollectorResponse
450+
x-fern-request-name: CreateAttributeCollectorResponseRequest
451+
/custom_channel_events/message:
452+
post:
453+
x-fern-sdk-group-name:
454+
- customChannelEvents
455+
x-fern-sdk-method-name: createMessage
456+
x-fern-request-name: CreateMessageRequest
457+
/custom_channel_events/new_conversation:
458+
post:
459+
x-fern-sdk-group-name:
460+
- customChannelEvents
461+
x-fern-sdk-method-name: createNewConversation
462+
x-fern-request-name: CreateNewConversationRequest
463+
/custom_channel_events/quick_reply_response:
464+
post:
465+
x-fern-sdk-group-name:
466+
- customChannelEvents
467+
x-fern-sdk-method-name: createQuickReplyResponse
468+
x-fern-request-name: CreateQuickReplyResponseRequest
445469
/data_attributes:
446470
get:
447471
x-fern-sdk-group-name:

0 commit comments

Comments
 (0)