Custom Channel

A Custom Channel connects any messaging system that can send and receive webhooks to the Resool shared inbox: your own app's chat, a local SMS gateway, an in-house live chat or a messaging platform Resool doesn't support natively. Your system POSTs customer messages to an inbound URL Resool gives you, and Resool POSTs every agent reply to a webhook URL you choose. Every request is signed with a shared secret, so both sides know the message is genuine.

#What you can do with a Custom Channel

In the Inbox

• Receive messages from your system as conversations, with text and up to 5 attachments per message.
• Reply from the inbox like on any channel. Each reply is POSTed to your replies webhook as signed JSON.
• See replies as delivered, read or failed when your system reports the status back.

On the channel

• Choose the Channel type (Messaging, SMS or Live chat) so conversations are labeled the right way.
• Generate a new signing secret at any time.

#Before you begin

• A developer who can make your system send signed HTTPS requests to Resool and receive Resool's requests.
• A public HTTPS endpoint in your system to receive replies (the Replies webhook URL).
• In Resool, only workspace Owners and Admins can create channels. A Custom Channel counts as one channel toward your plan's limit.

#How to create a Custom Channel

1. Go to Settings › Channels and click Add Channel.
2. Click Connect on one of the custom cards: Custom Channel (Business Messaging tab), Custom Channel (SMS) (SMS tab) or Custom Channel (Live Chat) (Live Chat tab). They create the same kind of channel with a different starting type.

Screenshot placeholder

Settings › Channels › Add Channel, All tab

The Channel Catalog with the Custom Channel card in Business Messaging, Custom Channel (SMS) in SMS and Custom Channel (Live Chat) in Live Chat, each with its webhook icon and Connect button.

File: screenshots/custom-channel-catalog.png

1. In the Connect a custom channel dialog, fill in:
   • Channel name: how the channel appears in Resool (up to 60 characters).
   • Channel type: Messaging, SMS or Live chat.
   • Replies webhook URL (optional): where Resool POSTs every reply. If you leave it empty, replies aren't delivered and show as failed in the inbox. You can add it later.
2. Click Create channel.
3. Save your signing secret appears with the Signing secret and the Inbound URL. Copy both and store the secret safely: it's shown only now.

Screenshot placeholder

Settings › Channels › Add Channel › Custom Channel › Create channel

The "Save your signing secret" step with its explanation, the Signing secret and Inbound URL fields with Copy buttons, and the "I saved it, continue" button.

File: screenshots/custom-channel-signing-secret.png

1. Click I saved it, continue. The channel page opens.

#How to send customer messages to Resool

POST each customer message as JSON to the Inbound URL, signed with your secret.

Body

{
  "event": "message",
  "contact": { "id": "cust-1", "name": "Nora", "email": "nora@example.com", "phone": "+15551234567" },
  "message": { "id": "m-1", "text": "Hello", "attachments": [] }
}

• contact.id (required): your system's ID for the customer. Resool keeps all messages with the same ID in one contact. name, email and phone are optional.
• message.text (up to 4,096 characters) and/or message.attachments (up to 5, each with a public url and optional name and mime). A message needs text or at least one attachment.
• message.id: your ID for the message. Required when you don't send a timestamp (see below).

Signature

Add the header X-Resool-Signature: sha256=HEX, where HEX is the HMAC-SHA256 of the exact request body, keyed with your signing secret.

For extra protection, also send X-Resool-Timestamp (Unix seconds) and sign TIMESTAMP.BODY instead of the body alone. Requests whose timestamp is more than 5 minutes old are refused. Without a timestamp, every customer message must carry its own message.id, so a replayed request can't create a duplicate.

The channel page shows a ready-to-run curl example under How it works › Send us a customer message.

#How replies reach your system

For each reply an agent (or an AI agent or workflow) sends, Resool POSTs JSON to your Replies webhook URL:

{
  "event": "message.created",
  "channel": { "id": "…", "name": "…", "flavor": "messaging" },
  "conversationId": "…",
  "contact": { "id": "cust-1" },
  "message": { "id": "<uuid>", "text": "Hi Nora", "attachments": [{ "name": "…", "mime": "…", "url": "…" }] }
}

• Headers: X-Resool-Event, X-Resool-Timestamp and X-Resool-Signature. Verify the signature the same way, over TIMESTAMP.BODY.
• contact.id is the ID you sent, so you know who to deliver the reply to.
• If delivery fails, Resool retries with the same message.id. Use it to ignore duplicates.

#Report delivery (optional)

To show delivery in the inbox, POST a status to the Inbound URL, signed the same way:

{ "event": "status", "messageId": "<message.id we sent>", "status": "delivered" }

status is delivered, read or failed. With failed, you can add an error (up to 300 characters).

#How to configure a Custom Channel

Open Settings › Channels and click Manage on the channel. The Configuration tab shows:

• Channel name.
• Inbound URL: where your system POSTs customer messages and statuses.
• Signing secret: hidden for your security. Click Generate a new secret if you lost it.
• Replies webhook URL and Channel type: change them and save with the save bar.
• How it works: the signing rules and copyable examples for Send us a customer message, What we send you for each reply and Report delivery (optional).

Screenshot placeholder

Settings › Channels › (custom channel) › Configuration

The Configuration tab with the Inbound URL and its Copy button, the Signing secret with the Generate a new secret button, the Replies webhook URL and Channel type fields, and the How it works section with the three code examples.

File: screenshots/custom-channel-configuration.png

#Generate a new signing secret

1. Click Generate a new secret.
2. Confirm in Generate a new signing secret?.
3. Copy the new secret. The old one stops working immediately, so update your system first or its messages will be refused.

Routing, auto-assignment and satisfaction surveys are set in Channel settings. To remove the channel, click Delete channel under Danger zone and confirm. Past conversations stay.

#Notes and limitations

• Up to 5 attachments per incoming message, each sent as a public http(s) URL.
• Message text up to 4,096 characters.
• Requests with a timestamp older than 5 minutes are refused.
• The inbound URL accepts up to 600 requests per minute per channel.
• Without a Replies webhook URL, replies are marked as failed.

#FAQ and troubleshooting

#Resool answers my request with 403

The signature didn't match, or the timestamp is more than 5 minutes off.

What you can do:

• Sign the exact bytes you send. Re-serializing the JSON after signing changes the body.
• If you send X-Resool-Timestamp, sign TIMESTAMP.BODY (with the dot) and keep your server clock in sync.
• Check that you're using the current secret, not one replaced by Generate a new secret.

#Resool answers my request with 400

The body doesn't match the format. Check that event is message or status, that contact.id is set, that the message has text or an attachment, and that message.id is set when you don't send a timestamp.

#Resool answers my request with 404

The inbound URL is wrong, or the channel was deleted or disabled. Copy the Inbound URL again from the channel page.

#Replies show as failed in the inbox

What you can do:

• Add a Replies webhook URL on the channel's Configuration tab.
• Make sure your endpoint is public, uses HTTPS and answers with a success status.
• If your system reports failed statuses, check the error you send.

#Can I use a Custom Channel for an SMS provider?

Yes. Choose the SMS channel type, have your SMS provider's webhooks forward incoming texts to the inbound URL, and send replies through the provider's API from your replies webhook. If you use Twilio, the built-in Twilio SMS channel is simpler.

#What's next?

• Developer API
• Webhooks
• Channel settings: routing, auto-assign and satisfaction surveys
• Twilio SMS Quick Start