Chat

POST/api/v1/chat/message

Send a message, get the reply. Keep the conversation_id to continue the thread. The worker must be a chat type with status active or training.

agent_iduuidrequired

messagestringrequired

1 to 10 000 chars.

conversation_iduuid

Omit on the first message, we make one. Send it back on every next message.

contact_namestring

Max 255.

contact_emailstring

contact_phonestring

Max 50.

metadataobject

Anything the worker should know about this visitor.

curl -X POST https://v2.heppu.ai/api/v1/chat/message \
  -H "x-api-key: hep_..." -H "Content-Type: application/json" \
  -d '{"agent_id":"6f0c…","message":"Do you deliver to Oulu?","contact_email":"ada@example.com"}'

200

{
  "data": {
    "conversation_id": "0b3f0e4c-…",
    "message_id": "msg_…",
    "response": "Yes, next day to Oulu. Want me to check a specific postcode?",
    "model": "gpt-5.6-terra",
    "usage": { "input_tokens": 812, "output_tokens": 96, "total_tokens": 908 },
    "processing_time_ms": 1423
  },
  "meta": { "timestamp": "…" }
}

Note the snake_case. This endpoint predates the rest and we kept it stable.

Synchronous. Typical reply is 1 to 4 seconds, hard cap 60. No streaming here, use the widget if you need tokens as they come.

Errors

Status	Message
400	`This endpoint only supports chat agents…` or `Agent is not available (status: inactive)`
404	`Agent not found or does not belong to your organization`
429	Chat worker is busy. Back off.
503	`Chat service temporarily unavailable`. Retry with backoff.

Conversations show up in the dashboard under Conversations with source api.

Errors

On this page