What you will build

Customers stay in their Voiceflow conversation while your team replies from Intercom. Your service translates the platform’s conversation operations and events into the live agent handoff system.

This is a developer implementation guide, not a native connector. The API approach has been reviewed against provider documentation; a live account test is required before rollout.

Before you begin

You need an Intercom app token with conversation access, a test contact, and an inbox teammate, an HTTPS service, and access to Custom Handoff in Voiceflow. Start with the shared connection starter. Choose one test customer and one support destination.

Keep the integration responsible for message delivery. Do not let an email delivery path and the Voiceflow relay both notify the customer unintentionally.

Implement the connection

Prepare the support workspace

Create or identify the customer contact in Intercom. Save its Intercom contact ID separately from your Voiceflow end-user ID. Pin the API version used by your app.

Confirm a teammate can receive and answer a manually created test conversation before adding Voiceflow.

Implement conversation creation

POST /conversations with a from contact and a customer-facing body. Save the conversation ID from the response.

Example provider request body for POST /conversations (replace illustrative IDs):

{
  "from": {
    "type": "user",
    "id": "INTERCOM_CONTACT_ID"
  },
  "body": "Customer requested help with an order."
}

Use the starter’s create(request, connectionId) hook. Persist the provider ID and connection ID together. Forward relevant context as an initial summary or supported private note; never inject internal metadata into customer-visible replies.

Forward customer messages

POST /conversations/{id}/reply as the customer contact using message_type: "comment", type: "user", intercom_user_id, and body.

Implement the starter’s message(providerConversationId, message) hook. Deduplicate the Voiceflow message id. For the first test, support text and explicitly reject unsupported files rather than acknowledging and dropping them.

Receive human replies

Subscribe to conversation.admin.replied and conversation closure events. Extract the new public reply, not every historical conversation part. Exclude private notes and customer replies.

After provider authentication succeeds, look up the mapped connection ID and send a normalized message.received event to the starter’s authenticated /events route. Include a stable provider event ID, timestamp and human display name. Do not manufacture an agent.joined event merely because a conversation was created.

Implement closure

Use Intercom’s conversation management operation to close the mapped conversation, with the appropriate admin identity. Verify that closure generates the expected callback.

Implement the end(providerConversationId) hook. Deliver conversation.ended for provider-initiated closure. Make both paths idempotent so a reflected closure cannot trigger an endless loop.

Connect and test in Voiceflow

Configure your service in Settings → Integrations → Custom Handoff, then follow Set up live agent handoff. Set Queue ID only when your service has a documented mapping. Publish to a test environment and use the actual customer channel.

Provider mapping

Store the contact ID used to create the conversation and reuse it for customer replies. Map conversation.admin.replied to a public human reply, and the provider’s actual close event to conversation.ended. The reply endpoint is POST /conversations/{id}/reply; customer reply fields differ from admin reply fields. See Intercom reply types.

Verify a complete handoff

Run this acceptance sequence with a teammate in Intercom:

Escalate and confirm exactly one conversation appears in the intended inbox.
Check the customer identity and escalation context.
Send “customer test 1” from Voiceflow and “human test 1” from the support inbox. Both must arrive once.
Add a private note; it must not reach the customer.
Replay the same customer-message ID and provider event ID; neither should duplicate a message.
Close from the support inbox and verify the configured return-to-AI path.
Repeat with invalid credentials and an unavailable provider; verify the fallback.

If messages disappear, inspect the provider delivery log, the ID mapping and Voiceflow callback response in that order. A successful create call alone does not establish that the connection works.

Reference and next steps

Provider setup/API documentation · Provider messages/events documentation

Connection API · Event contract · Troubleshooting

Before production, replace in-memory state with durable storage, implement the provider’s retry/refresh rules, and test attachment and routing support only if your deployment needs them.

Connect Voiceflow to Intercom