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.
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.
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'.
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.
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.
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.
Known gotchas
Full programmatic creation of all bot steps via API is not available on all Intercom plans — the API surface for Workflows varies by contract tier; confirm what endpoints your plan exposes.
Custom conversation attributes set via API must be defined as writable in your Data Attributes settings; read-only attributes cannot be updated by API calls.
Operator rules that trigger bot flows evaluate conditions at conversation-start time — updating an attribute after a conversation begins will not retroactively re-trigger a completed rule.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp