Skip to content

Commit ca8bb06

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 7afd4f1 commit ca8bb06

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
@@ -17514,6 +17714,58 @@ components:
1751417714
type: string
1751517715
description: Name of the action
1751617716
example: Jira Create Issue
17717+
custom_channel_attribute:
17718+
title: Custom Channel - Attribute
17719+
type: object
17720+
required:
17721+
- id
17722+
- value
17723+
properties:
17724+
id:
17725+
type: string
17726+
description: Identifier for the attribute being collected.
17727+
value:
17728+
type: string
17729+
description: Value provided by the user for the attribute.
17730+
custom_channel_base_event:
17731+
title: Custom Channel - Base Event
17732+
type: object
17733+
properties:
17734+
event_id:
17735+
type: string
17736+
description: Unique identifier for the event.
17737+
conversation_id:
17738+
type: string
17739+
description: Identifier for the conversation in your system.
17740+
contact:
17741+
$ref: '#/components/schemas/custom_channel_contact'
17742+
required:
17743+
- event_id
17744+
- conversation_id
17745+
- contact
17746+
custom_channel_contact:
17747+
title: Custom Channel - Simplified Contact
17748+
type: object
17749+
required:
17750+
- type
17751+
- external_id
17752+
- name
17753+
- email
17754+
properties:
17755+
type:
17756+
type: string
17757+
enum: [user, lead]
17758+
description: Type of contact, must be "user" or "lead".
17759+
external_id:
17760+
type: string
17761+
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.
17762+
name:
17763+
type: string
17764+
description: Name of the contact.
17765+
email:
17766+
type: string
17767+
format: email
17768+
description: Email address of the contact.
1751717769
custom_action_finished:
1751817770
title: Part type - custom_action_finished
1751917771
type: object
@@ -18062,6 +18314,13 @@ components:
1806218314
-
1806318315
example: Customer
1806418316
nullable: true
18317+
intercom_version_unstable:
18318+
description: Unstable Intercom API version. Used for closed beta endpoints.
18319+
type: string
18320+
example: unstable
18321+
default: unstable
18322+
enum:
18323+
- unstable
1806518324
linked_object_list:
1806618325
title: Linked Objects
1806718326
type: object
@@ -20592,12 +20851,54 @@ components:
2059220851
application/json:
2059320852
examples:
2059420853
ObjectNotFound:
20854+
value:
20855+
type: error.list
20856+
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
20857+
errors:
20858+
- code: not_found
20859+
message: Object not found
20860+
CustomObjectNotFound:
2059520861
value:
2059620862
type: error.list
2059720863
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
2059820864
errors:
2059920865
- code: not_found
2060020866
message: Custom object instance not found
20867+
IntegrationNotFound:
20868+
value:
20869+
type: error.list
20870+
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
20871+
errors:
20872+
- code: data_invalid
20873+
message: Integration not found
20874+
schema:
20875+
"$ref": "#/components/schemas/error"
20876+
ValidationError:
20877+
description: Validation Error
20878+
content:
20879+
application/json:
20880+
examples:
20881+
ValidationError:
20882+
value:
20883+
type: error.list
20884+
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
20885+
errors:
20886+
- code: data_invalid
20887+
message: Invalid or duplicated record reference
20888+
schema:
20889+
"$ref": "#/components/schemas/error"
20890+
BadRequest:
20891+
description: Bad Request
20892+
content:
20893+
application/json:
20894+
examples:
20895+
BadRequest:
20896+
value:
20897+
type: error.list
20898+
request_id: 12a938a3-314e-4939-b773-5cd45738bd21
20899+
errors:
20900+
- code: data_invalid
20901+
message: Contact not found or could not be created
2060120902
schema:
2060220903
"$ref": "#/components/schemas/error"
2060320904
servers:
@@ -20640,6 +20941,13 @@ tags:
2064020941
externalDocs:
2064120942
description: What is a conversation?
2064220943
url: https://www.intercom.com/help/en/articles/4323904-what-is-a-conversation
20944+
- name: Custom Channel Events
20945+
description: |
20946+
With the **closed beta** "Custom Channel" integration, you can bring Fin and Intercom capabilities to your own platform via API, enabling powerful custom integrations.
20947+
20948+
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.
20949+
20950+
> **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.
2064320951
- name: Custom Object Instances
2064420952
description: |
2064520953
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: notifyAttributeCollectorResponse
450+
x-fern-request-name: NotifyAttributeCollectorResponseRequest
451+
/custom_channel_events/message:
452+
post:
453+
x-fern-sdk-group-name:
454+
- customChannelEvents
455+
x-fern-sdk-method-name: notifyMessage
456+
x-fern-request-name: NotifyMessageRequest
457+
/custom_channel_events/new_conversation:
458+
post:
459+
x-fern-sdk-group-name:
460+
- customChannelEvents
461+
x-fern-sdk-method-name: notifyNewConversation
462+
x-fern-request-name: NotifyNewConversationRequest
463+
/custom_channel_events/quick_reply_response:
464+
post:
465+
x-fern-sdk-group-name:
466+
- customChannelEvents
467+
x-fern-sdk-method-name: notifyQuickReplyResponse
468+
x-fern-request-name: NotifyQuickReplyResponseRequest
445469
/data_attributes:
446470
get:
447471
x-fern-sdk-group-name:

0 commit comments

Comments
 (0)