Configure an Intercom Custom Bot (Fin or Series) workflow via API

Steps

1. In the Intercom Developer Hub, ensure your app has the 'Manage Articles' and 'Read/Write Conversations' scopes if your bot needs to search Help Center content or create conversations.
2. Use the Intercom UI (Operator or Series builder) or the Workflows API (if available on your plan) to create a bot flow — note that full programmatic bot step creation is limited; most bot logic is authored in the UI, with API used for triggering and data injection.
3. Use the Custom Attributes API (POST /data_attributes) to define user or conversation attributes that your bot flow will read to branch logic — supply 'name', 'model' (contact or conversation), and 'data_type'.
4. Trigger a specific bot workflow for a contact by updating a conversation's custom attribute via PATCH /conversations/{id} with the attribute value that your Operator rule conditions monitor.
5. Listen for bot-to-human handoff by subscribing to the 'conversation.admin.assigned' webhook topic — your handler receives the conversation ID when a bot transfers to an agent.
6. To inject context into the handoff, use PATCH /conversations/{id} to add an internal note with a 'type': 'note' message body before the assignment event.