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_idYesWorkspace (tenant) UUID.
contact_idNoExisting CRM contact UUID when known.
conversation_id / sessionNoStable conversation / session id. Keep it constant for the whole dialogue — never append timestamps.
channelYesTransport context, e.g. web, whatsapp, phone, email, api.
event_typeYese.g. message, message.received, appointment.requested.
payloadNoEvent data (message text, appointment fields, etc.).
request_idNoIdempotency / 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:

  • channel tells 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.

Need a workspace? Start from Pricing for a custom offer, or return to the introduction.