Web channel overview

The web channel is a server-to-server messaging channel. Your backend posts customer messages to the Genudo receiver, and Genudo posts the AI reply back to a callback_url you control, signed with HMAC-SHA256.

Unlike the widget, Genudo hosts no UI here — you own the chat surface entirely.

Before you start

Create the channel and configure it in the Genudo Console: pick the pipeline, set the callback_url, and optionally restrict allowed_origins / allowed_ips. The Console then shows you:

Value	Use
client_id	Basic auth username for every request below
client_secret	Basic auth password and the HMAC key for verifying callbacks
messages_webhook	The receiver URL your backend posts messages to

Channel setup is not part of this API — it is done in the Console.

The flow

1. Open a conversation     POST {api}/user/web-chat/initiate   → contact_id + socket token
2. Send a message          POST {receiver}/web-chat/message    → message_id
3. Receive the reply       POST your callback_url              ← signed by Genudo
4. Read history            GET  {api}/user/messages/webchat?conversation_id={conversation_id}

Step 1 is optional — the receiver creates the contact and conversation on the first inbound message anyway. Call it when you want to validate the pipeline, subscription and credits before accepting customer traffic, register the contact's name / email / phone, or get a socket subscription so you can render replies live instead of waiting on the webhook.

Authentication

Every endpoint in this section uses the channel's credentials, as HTTP Basic auth:

Authorization: Basic base64(client_id:client_secret)

These authenticate the channel, not a user, and are what your backend ships to production. They are unrelated to the account API tokens described in Authentication.

Two base URLs

Placeholder	What it is	Where to find it
{api}	The console API, e.g. https://api.genudo.ai/api	Fixed per environment
{receiver}	The message receiver, e.g. https://receiver.genudo.ai	The channel's messages_webhook in the Console

Inbound messages go to {receiver}. Everything else goes to {api}. Posting to the wrong host is the most common setup mistake.

Identifiers

Id	Who creates it	Meaning
client_id	Genudo, when the channel is created	Public id of the channel, prefix wc_. Also the Basic auth username.
client_secret	Genudo, when the channel is created	Basic auth password and the HMAC key for verifying callbacks.
contact_id	You	Your own chat/session id. Send the same value on every message in a conversation; it comes back on the reply webhook.
conversation_id	Genudo	Numeric id used for history and the socket room.
message_id	Genudo	Mongo id of a stored message. The inbound and reply ids are different.

Security

Every callback is signed — see Reply webhook. Verify the signature on every request; the URL is otherwise an open endpoint.

allowed_origins and allowed_ips on the channel additionally restrict who may post inbound messages. Both default to empty, which means allow all, not deny all.