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-6.1-sol",
    "usage": { "input_tokens": 812, "output_tokens": 96, "total_tokens": 908 },
    "processing_time_ms": 1423,
    "ai_generated": true,
    "digital_source_type": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia"
  },
  "meta": { "timestamp": "…" }
}

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

We may add new fields to this response without notice. Adding a field doesn't count as a breaking change, so ignore any field you don't recognise.

AI-generated marking

The response text is written by an AI model. The EU AI Act (Article 50(2)) requires AI-generated text to be marked in a form software can read, so every successful reply carries three marks:

ai_generatedboolean

Always true.

digital_source_typestring

http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia, the IPTC standard term for "created using generative AI".

AI-Disclosureheader

mode=machine-generated: a model wrote the text and no person reviewed it before it was sent.

If you store the reply or pass it on to another system, keep these marks with it. Error responses contain no AI text, so they carry none of the three.

Synchronous. A typical reply takes 1 to 4 seconds; a turn that calls tools can take longer. The knowledge lookup and the model calls get 120 seconds together, and past that the request is answered with 504. 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`
404	`Conversation not found`. The `conversation_id` belongs to another organization.
429	Chat worker is busy. Back off.
503	`Chat service temporarily unavailable`. Retry with backoff.
504	`The chat turn timed out. The agent may already have acted on this message; check the conversation before sending it again.` The message may have been saved and a tool may have run, so check the conversation before resending it.

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

AI-generated markingCopy Anchor Link

ErrorsCopy Anchor Link

On this page

AI-generated marking

Errors