Initiate a conversation

Opens — or resumes — a conversation before the first message is sent.

POST {api}/user/web-chat/initiate
Authorization: Basic base64(client_id:client_secret)

Optional: the receiver creates the contact and conversation on the first inbound message anyway. Call it when you want to:

• fail fast if the channel is not linked to a pipeline, or the account has no subscription or credits, instead of posting blind and waiting for a callback that never comes
• register the contact's name / email / phone up front — the message endpoint does not accept them
• get a socket subscription so you can render replies live rather than waiting on the webhook

curl -X POST "https://api.genudo.ai/api/user/web-chat/initiate" \
  -u "wc_YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "contact_id": "user-abc-123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  }'

Request body

All fields are optional.

Field	Type	Rules
contact_id	string	Max 255. Your own chat/session id. Generated as a ULID if omitted.
name	string	Max 255. Only applied when the contact has no name yet.
email	string	Valid email, max 255. Only applied when the contact has no email yet.
phone	string	Max 30. Only applied when the contact has no phone yet.

Identity fields never overwrite existing values.

Response

{
  "status": true,
  "code": 200,
  "validation": [],
  "message": "Web chat conversation initiated",
  "data": {
    "contact_id": "user-abc-123",
    "conversation_id": 221416,
    "messages_webhook": "https://receiver.genudo.ai/web-chat/message",
    "channel": "conversation.221416",
    "token": "eyJhbGciOi…",
    "socket_url": "https://receiver.genudo.ai",
    "app_key": "KVEomYJbKBrOApiT0mxVZrbrx4z8ahMN",
    "event": "new_message"
  }
}

Reuse contact_id verbatim

Send the returned contact_id as contact_id on every message. It is what ties messages to this conversation, and it comes back on the reply webhook.

Idempotent — calling it again with the same contact_id resumes the same conversation rather than creating a second one.

Watching replies over socket.io

import { io } from 'socket.io-client'

const socket = io(socket_url)

socket.on('connect', () => {
  socket.emit('join-channel', { channel, app_key, token })
})

socket.on('new_message', (messages) => {
  // messages[0].message  → the reply text
  // messages[0].cost     → the cost charged to your account
})

An invalid token disconnects the socket rather than returning an error.

Errors

Code	Message
401	Invalid client credentials
422	This endpoint is only available for web channels.
422	Channel is not linked to any pipeline
400	No subscription found / No credits found / No stages found for this pipeline