API reference
Most businesses use the managed channels (widget, WhatsApp, phone) with zero custom code. The Events API is for integrators who need to send messages or actions into the same AI Operations brain from their own systems.
Design principle
POST /api/v1/events is the programmatic entry into the operations department. The channel field selects the transport context; it does not invent a separate business logic stack. Booking, identity, and knowledge rules remain shared with Web, WhatsApp, and Voice.
Endpoint
POST /api/v1/events
Request body: JSON. Response: JSON. Authenticate and scope requests to your tenant as provisioned by Praigen.
Request body
| Field | Required | Description |
|---|---|---|
tenant_id | Yes | Workspace (tenant) UUID. |
contact_id | No | Existing CRM contact UUID when known. |
conversation_id / session | No | Stable conversation / session id. Keep it constant for the whole dialogue — never append timestamps. |
channel | Yes | Transport context, e.g. web, whatsapp, phone, email, api. |
event_type | Yes | e.g. message, message.received, appointment.requested. |
payload | No | Event data (message text, appointment fields, etc.). |
request_id | No | Idempotency / correlation id. |
Compatibility: customer_id is accepted as tenant_id; user_id as contact_id. Response field agent remains for compatibility and refers to an internal runtime class — not a separate product you hire per channel.
Example request
curl -X POST https://praigen.com/api/v1/events \
-H "Content-Type: application/json" \
-d '{
"tenant_id": "550e8400-e29b-41d4-a716-446655440000",
"channel": "web",
"event_type": "message",
"conversation_id": "session-stable-id",
"payload": { "message": "Hi", "text": "Hi" }
}'
Success response (200)
{
"ok": true,
"agent": "ChatAgent",
"reply": {
"text": "Reply text from the operations assistant.",
"tool_results": []
}
}
Error response (4xx / 5xx)
{
"ok": false,
"error": "tenant_id is required",
"details": null
}
Channel context (not separate products)
Older docs described routing as “pick Email Employee vs Appointment Employee vs Website Chat Employee.” Prefer thinking in omnichannel terms:
channeltells the platform where the customer is talking- Appointment intents still hit the shared calendar engine
- Email / chat / API contexts share contacts and knowledge for the business
For website traffic, prefer the official widget rather than reinventing the chat UI against Events API.