API channel: bring your own messaging channel

What is the API channel?

It connects any system that can make HTTP requests to your WorkflowHQ inbox. Your server POSTs each incoming message to an endpoint we give you; the conversation appears in your inbox like any other channel; and every reply, whether from your AI agent or a teammate typing in the inbox, is POSTed to a webhook URL on your server so you can pass it back to your user. Available on paid plans.

How do I set one up?

1. Open Settings, then Integrations, then Channels, and choose Create API channel.
2. Give it a name, enter your webhook URL (an https endpoint on your server, or an n8n or Make webhook), and pick an agent, or choose no agent to have humans reply from the inbox.
3. Save the credentials on the next screen: the endpoint, the API key and the webhook signing secret are shown exactly once. If you lose them, delete the channel and create it again.

How do I send a message in?

POST to your channel's endpoint with the API key as a bearer token. externalId identifies the end user - the same value always lands in the same conversation. messageId is your transport's message id and makes retries safe: a repeated messageId is ignored. contact is optional and links the sender to a CRM contact; attributes carries values for your own custom fields and rejects keys you have not defined.

curl -X POST https://app.workflowhq.co/api/v1/channels/CHANNEL_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-42",
    "messageId": "unique-per-message",
    "text": "Hi, do you have a 10am slot tomorrow?",
    "contact": { "name": "Asha Rao", "phone": "+919876543210" }
  }'

How do replies reach me?

We POST every reply to your webhook URL as JSON with the externalId, the text, and whether an agent or a teammate sent it. Each delivery carries an x-workflowhq-signature header: sha256=hex(HMAC-SHA256(raw body, your signing secret)). Recompute it on your server and reject anything that does not match, so nobody who discovers your URL can forge replies. If your webhook stops accepting deliveries, the channel shows a webhook failing badge in Settings, and replies keep landing in your inbox either way.

Does the AI answer automatically?

If the channel has an agent, yes: the agent answers with the same knowledge and prompt it uses everywhere else, and each AI reply uses one chat credit. With no agent bound, messages simply land in the inbox for your team, which uses no credits. Pausing the AI on a single conversation from the inbox works here exactly as it does for web chat.