Events

Send messages to AI Agents and receive responses

Health check

get

Returns a simple status object to verify the service is running.

Responses

200

Service is healthy

application/json

statusstringOptionalExample: ok

get

/api/events

HTTPcURLJavaScriptPython

GET /api/events HTTP/1.1
Host: bot-v5.helvia.ai
Accept: */*

200

Service is healthy

{
  "status": "ok"
}

Send a message to an AI Agent

post

Send a text or postback message to an AI Agent and receive the agent's response(s) synchronously. Use this endpoint for all conversational interactions.

Usage flow:

1. Trigger the greeting with a postback message (type: "node", data: "greeting") to start a new session

2. Send text messages for each conversation turn

3. Use a consistent sender.id to maintain session context across messages

Authorizations

BearerAuth

AuthorizationstringRequired

API Token from the console (Designer → Deployments → API → API Token)

Body

application/json

handlestringRequired

Agent deployment identifier (from console: Designer → Deployments → API → Identifier)

timestampnumberOptional

Unix timestamp in milliseconds

languagestringOptional

Language code override (e.g. "EN", "EL", "DE")

Responses

200

Agent response(s) returned successfully

application/json

statusstring · enumOptionalExample: okPossible values:

400

Validation error

application/json

401

Authentication failed

application/json

403

Token handle mismatch

application/json

500

Server error

application/json

post

/api/events

HTTPcURLJavaScriptPython

POST /api/events HTTP/1.1
Host: bot-v5.helvia.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "handle": "my-agent-handle",
  "message": {
    "payload": {
      "type": "node",
      "data": "greeting"
    }
  },
  "sender": {
    "id": "user-123"
  }
}

Trigger greeting (start new session)Send a text messageText message with metadata and language

{
  "status": "ok",
  "result": {
    "responses": [
      {
        "id": "TX_b8eb307f-cf33-48fb-bc51-a0e7e6a7d817",
        "type": "text",
        "options": [
          "Hi! I'm the Productivity Coach."
        ],
        "altText": "Hi! I'm the Productivity Coach."
      },
      {
        "id": "TX_1bfda168-dd49-4dc0-b9fc-56ce9cb5d141",
        "type": "text",
        "options": [
          "How can I help you today?"
        ],
        "altText": "How can I help you today?"
      }
    ]
  }
}