` (note: h3-h6 appear as h2) - Text formatting: `` (bold), `` (italic) - Links: `` - Images: `![]()
` (can be linked) - Line breaks: `
` - Code blocks: `` - Lists: `` (unordered), `` (ordered) Example HTML: ```html Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Normal paragraph with a link, bold, italic, and a line break
right here.
- Unordered item 1
- Unordered item 2
- Ordered item 1
- Ordered item 2
console.log('hello world!'); ``` --- ## **Agent & Conversation Management** **Q: Does the get_agent API need conversation ID parameters?** **A:** No. `get_agent` is only used during initial Fin configuration to select which agent represents Fin in the external system. You can return a single hardcoded bot agent here. **Q: How will Intercom inform us that a human agent needs to join a conversation?** **A:** Intercom sends an `update_conversation` call with `assignee_id` set to null. --- ## **Attributes & Data Structure** **Q: Are conversation-level attributes separate from user attributes?** **A:** Yes. Structure is: ```json { "conversation": { "attributes": { // conversation-specific data like locale, topic, sentiment, order_id }, "user": { "id": "...", "type": "end-user", "name": "...", "attributes": { // user-specific custom attributes } } } } ``` **Q: When EndUser attributes change, will update_conversation be called?** **A:** Yes. Conversation and user state is synchronized on each inbound/outbound event (new messages, user data updates via workflows, for example an Email Collector step, etc.). --- ## **Request Verification** **Q: How do I verify that incoming requests are genuine?** **A:** We provide two extra headers on our requests to your servers: - `X-Fin-Request-Timestamp` - This is the timestamp of the request (in seconds since epoch). You may use this to reject requests that are too old. - `X-Fin-Signature` - This is the SHA256 HMAC signature of `{timestamp}:{request_body}`. You may use this to verify the authenticity of the request from us. Note as there is no body for GET requests, we instead sign: `{timestamp}:{request_params_sorted_alphabetically}`. The HMAC key used to validate the signature is found in your deployment settings. --- ## **Connecting Fin to your endpoints** **1** - Navigate to the Deploy > Fin Messenger section in your Fin Workspace. 
**2** - You can give your integration a name to identify it. We will support multiple different connections later (e.g. for multiple different sub-brands you may have) Please note that "Channel type" is currently static with the value "Fin messenger". We will support other channel types at a later time. Make note of the *Identifier* value you are given here. This is the identifer you must use in your webhooks back to the Fin system. **3** - Configure your API endpoint URLs. What these endpoints are for and the request/response format is described in the rest of these docs. 
**4** - Set up authentication for your endpoints. By default we use OAuth for this. Choose the "OAuth token settings" option and configure the OAuth connection with your server. Note, you may allowlist Intercom's IP address ranges — see [Intercom IP addresses](/docs/build-an-integration/learn-more/ip-allowlisting/). 
**5** - Note the webhook secret generated for you. This must be provided in the X-Webhook-Key header in webhook requests to the Fin system. 
**6** - Choose a agent from your system to attribute Fin's replies to. When Fin generate a response for the customer, we will use the ID of the agent chosen here when creating messages in your system. 
**7** - Finally, when you've configured your workflow and installed the Fin Messenger you're ready to activate Fin. 
- [Fin Custom Helpdesk API](https://developers.intercom.com/docs/guides/fin-custom-helpdesk/api.md): The Fin Custom Helpdesk API allows you to integrate your custom helpdesk with Fin through a standardized set of API endpoints and webhooks.
- [Card Creation Options](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/card-creation-options.md)
- [Contact](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/contact.md)
- [Context](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/context.md)
- [Current Canvas](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/current-canvas.md)
- [Input Values](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/input-values.md)
- [Canvas](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/canvas.md)
- [Content](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/content.md)
- [Event](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/event.md)
- [Results](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/results.md)
- [Stored Data](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/stored-data.md)
- [Error Codes](https://developers.intercom.com/docs/references/preview/rest-api/errors/error-codes.md)
- [Error Objects](https://developers.intercom.com/docs/references/preview/rest-api/errors/error-objects.md)
- [HTTP Responses](https://developers.intercom.com/docs/references/preview/rest-api/errors/http-responses.md)
- [Intercom API](https://developers.intercom.com/docs/references/2.10/rest-api/api.intercom.io.md): The intercom API reference.
- [Rate Limiting](https://developers.intercom.com/docs/references/preview/rest-api/errors/rate-limiting.md)
- [Intercom API](https://developers.intercom.com/docs/references/2.11/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.12/rest-api/api.intercom.io.md): The Intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.13/rest-api/api.intercom.io.md): The Intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.15/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.7/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.8/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.9/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io.md): The intercom API reference.
- ` (unordered), `
- Unordered item 1
- Unordered item 2
- Ordered item 1
- Ordered item 2
- ` (ordered) Example HTML: ```html
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Normal paragraph with a link, bold, italic, and a line break
right here.
console.log('hello world!'); ``` --- ## **Agent & Conversation Management** **Q: Does the get_agent API need conversation ID parameters?** **A:** No. `get_agent` is only used during initial Fin configuration to select which agent represents Fin in the external system. You can return a single hardcoded bot agent here. **Q: How will Intercom inform us that a human agent needs to join a conversation?** **A:** Intercom sends an `update_conversation` call with `assignee_id` set to null. --- ## **Attributes & Data Structure** **Q: Are conversation-level attributes separate from user attributes?** **A:** Yes. Structure is: ```json { "conversation": { "attributes": { // conversation-specific data like locale, topic, sentiment, order_id }, "user": { "id": "...", "type": "end-user", "name": "...", "attributes": { // user-specific custom attributes } } } } ``` **Q: When EndUser attributes change, will update_conversation be called?** **A:** Yes. Conversation and user state is synchronized on each inbound/outbound event (new messages, user data updates via workflows, for example an Email Collector step, etc.). --- ## **Request Verification** **Q: How do I verify that incoming requests are genuine?** **A:** We provide two extra headers on our requests to your servers: - `X-Fin-Request-Timestamp` - This is the timestamp of the request (in seconds since epoch). You may use this to reject requests that are too old. - `X-Fin-Signature` - This is the SHA256 HMAC signature of `{timestamp}:{request_body}`. You may use this to verify the authenticity of the request from us. Note as there is no body for GET requests, we instead sign: `{timestamp}:{request_params_sorted_alphabetically}`. The HMAC key used to validate the signature is found in your deployment settings. --- ## **Connecting Fin to your endpoints** **1** - Navigate to the Deploy > Fin Messenger section in your Fin Workspace. **2** - You can give your integration a name to identify it. We will support multiple different connections later (e.g. for multiple different sub-brands you may have) Please note that "Channel type" is currently static with the value "Fin messenger". We will support other channel types at a later time. Make note of the *Identifier* value you are given here. This is the identifer you must use in your webhooks back to the Fin system. **3** - Configure your API endpoint URLs. What these endpoints are for and the request/response format is described in the rest of these docs. **4** - Set up authentication for your endpoints. By default we use OAuth for this. Choose the "OAuth token settings" option and configure the OAuth connection with your server. Note, you may allowlist Intercom's IP address ranges — see [Intercom IP addresses](/docs/build-an-integration/learn-more/ip-allowlisting/). **5** - Note the webhook secret generated for you. This must be provided in the X-Webhook-Key header in webhook requests to the Fin system. **6** - Choose a agent from your system to attribute Fin's replies to. When Fin generate a response for the customer, we will use the ID of the agent chosen here when creating messages in your system. **7** - Finally, when you've configured your workflow and installed the Fin Messenger you're ready to activate Fin.
- [Fin Custom Helpdesk API](https://developers.intercom.com/docs/guides/fin-custom-helpdesk/api.md): The Fin Custom Helpdesk API allows you to integrate your custom helpdesk with Fin through a standardized set of API endpoints and webhooks.
- [Card Creation Options](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/card-creation-options.md)
- [Contact](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/contact.md)
- [Context](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/context.md)
- [Current Canvas](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/current-canvas.md)
- [Input Values](https://developers.intercom.com/docs/references/preview/canvas-kit/requestobjects/input-values.md)
- [Canvas](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/canvas.md)
- [Content](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/content.md)
- [Event](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/event.md)
- [Results](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/results.md)
- [Stored Data](https://developers.intercom.com/docs/references/preview/canvas-kit/responseobjects/stored-data.md)
- [Error Codes](https://developers.intercom.com/docs/references/preview/rest-api/errors/error-codes.md)
- [Error Objects](https://developers.intercom.com/docs/references/preview/rest-api/errors/error-objects.md)
- [HTTP Responses](https://developers.intercom.com/docs/references/preview/rest-api/errors/http-responses.md)
- [Intercom API](https://developers.intercom.com/docs/references/2.10/rest-api/api.intercom.io.md): The intercom API reference.
- [Rate Limiting](https://developers.intercom.com/docs/references/preview/rest-api/errors/rate-limiting.md)
- [Intercom API](https://developers.intercom.com/docs/references/2.11/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.12/rest-api/api.intercom.io.md): The Intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.13/rest-api/api.intercom.io.md): The Intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.15/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.7/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.8/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/2.9/rest-api/api.intercom.io.md): The intercom API reference.
- [Intercom API](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io.md): The intercom API reference.