Channels

A channel is one place where customers write to the business: a website chat, a mailbox, a phone number or a messaging account. A business connects each channel with its own account. See the channels API.

Kinds of channel

Each channel has a kind. Read the kinds on your server, what each supports and what its connect step needs with GET /api/v1/channels/kinds.

curl https://api.impellabs.tech/api/v1/channels/kinds \
  -H "Authorization: Bearer YOUR_API_KEY"

Each entry has kind, label, supports, window_hours, available and connect.

Connect a channel

The member who connects a channel owns it. They connect it with POST /api/v1/channels/connect/{kind}. The body depends on the kind. Some kinds ask for one more value, and then the answer is 409 with the field that is missing and a pending_id. Send pending_id and the value within 15 minutes to finish. Credentials go in and never come back in a response.

One agent answers

A channel has one agent that answers on it. Set it with PATCH:

curl -X PATCH https://api.impellabs.tech/api/v1/channels/CHANNEL_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_ID"}'

Send null to unbind. With no agent, nobody answers yet.

Who the agent answers

The settings of a channel say who the agent answers and how its replies feel. Send PATCH with a settings object. Only the keys you send change.

Key	Meaning
`who`	`all`, `selected` (only the test addresses) or `rollout` (test addresses and `percent` of the others).
`test`	Customer addresses the agent always answers. Phone channels use E.164.
`percent`	0 to 100. Used by `rollout`. The same customer always falls on the same side.
`reply_wait`	Seconds to wait for more lines before the agent answers.
`read_receipts`, `typing`, `rich`	On or off, where the channel supports them.
`keep_team`, `keep_team_days`	Keep customers the team wrote to before the agent went live with the team.

A change to who, test or percent applies to new conversations.

Who can read a channel

A channel is private to the member who connected it until they share it. Share it with chosen members, with departments or with everyone. Sharing sets who reads the conversations. It does not change who the agent answers.

curl -X PATCH https://api.impellabs.tech/api/v1/channels/CHANNEL_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"sharing": {"mode": "people", "members": ["MEMBER_ID"], "departments": []}}}'

mode is private, people or everyone.

Only the owner of the channel shares it with more people. A person who manages channels can narrow or stop sharing.
A channel that was connected before sharing existed has no sharing value. Owners and admins can read it, as before.
People who read a channel see the replies of the agent and its name. They do not see its instructions unless the agent is shared with them too. The channel response has agent_hidden for its owner when this is the case.

Health

GET /api/v1/channels/{channel_id} returns status, problem, health and checked_at. Ask the provider again with POST /api/v1/channels/{channel_id}/verify. A channel.status_changed event tells your systems when a channel is switched on, paused, fails or is removed.

Get started

Concepts