Intercom integration

In short

Find contacts, read conversations, reply and send messages. Connect it on the Integrations page; your app then calls Intercom through Sapilon without ever holding an Intercom credential.

Lets your app search, create and update contacts, read and search conversations, reply to them as an admin and start new messages, with an Intercom access token.

Connecting

On the Integrations page choose Connect on Intercom and fill in:

Access token — Intercom → Settings → Integrations → Developer Hub → your app → Configure → Authentication → Access token.

Sapilon checks the key with the provider before it saves it, and stores it encrypted; it is never shown again.

Workspaces hosted in Intercom’s EU or Australian regions are not supported yet.

What your app can do

Only these requests are available; anything else is refused.

GET /admins
GET|POST /contacts
GET|PUT /contacts/*
POST /contacts/search
GET /conversations
GET /conversations/*
POST /conversations/search
POST /conversations/*/reply
POST /messages

How the agent uses it

Use integrations.request('intercom', …); paths are relative to https://api.intercom.io and the Intercom-Version header is added for you.

GET /admins — teammates; replies need an admin_id.
GET|POST /contacts, GET|PUT /contacts/{id} — Example: { method: 'POST', path: '/contacts', body: { role: 'user', email: 'sara@acme.com', name: 'Sara' } }.
POST /contacts/search — Example: { method: 'POST', path: '/contacts/search', body: { query: { field: 'email', operator: '=', value: 'sara@acme.com' } } }.
GET /conversations, GET /conversations/{id}, POST /conversations/search — Example: { method: 'POST', path: '/conversations/search', body: { query: { field: 'state', operator: '=', value: 'open' } } }.
POST /conversations/{id}/reply — Example: { method: 'POST', path: '/conversations/123/reply', body: { message_type: 'comment', type: 'admin', admin_id: '42', body: 'Fixed now' } } (message_type: 'note' for an internal note).
POST /messages — start a conversation. Example: { method: 'POST', path: '/messages', body: { message_type: 'email', subject: 'Your order', body: 'Shipped', from: { type: 'admin', id: '42' }, to: { type: 'user', id: 'c1' } } }.

Deleting is not allowed.