# Events

Send messages to AI Agents and receive responses

## Health check

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

```json
{"openapi":"3.0.3","info":{"title":"Helvia.ai Bot API","version":"1.0.0"},"tags":[{"name":"Events","description":"Send messages to AI Agents and receive responses"}],"servers":[{"url":"https://bot-v5.helvia.ai","description":"Production"}],"paths":{"/api/events":{"get":{"tags":["Events"],"summary":"Health check","description":"Returns a simple status object to verify the service is running.","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}}}}}}}
```

## Send a message to an AI Agent

> 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

```json
{"openapi":"3.0.3","info":{"title":"Helvia.ai Bot API","version":"1.0.0"},"tags":[{"name":"Events","description":"Send messages to AI Agents and receive responses"}],"servers":[{"url":"https://bot-v5.helvia.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API Token from the console (Designer → Deployments → API → API Token)"}},"schemas":{"EventRequest":{"type":"object","required":["handle","message"],"properties":{"handle":{"type":"string","description":"Agent deployment identifier (from console: Designer → Deployments → API → Identifier)"},"message":{"$ref":"#/components/schemas/Message"},"sender":{"$ref":"#/components/schemas/Sender"},"timestamp":{"type":"number","description":"Unix timestamp in milliseconds"},"language":{"type":"string","description":"Language code override (e.g. \"EN\", \"EL\", \"DE\")"},"tagOperations":{"$ref":"#/components/schemas/TagOperations"},"options":{"$ref":"#/components/schemas/RequestOptions"}}},"Message":{"type":"object","description":"Either a text message (with `text`) or a postback message (with `payload`). Exactly one must be provided.","properties":{"text":{"type":"string","description":"User's text message"},"payload":{"$ref":"#/components/schemas/Postback"},"contexts":{"type":"array","items":{"type":"string"},"description":"Optional context strings"}}},"Postback":{"type":"object","required":["type","data"],"description":"Trigger a specific flow node, intent, or action","properties":{"type":{"type":"string","enum":["node","intent","action"],"description":"Type of postback trigger"},"data":{"description":"Target identifier — node ID (e.g. \"greeting\"), intent name, or action object","oneOf":[{"type":"string"},{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object"}}}}]}}},"Sender":{"type":"object","description":"Identifies the end user. Use a consistent ID per user to maintain conversation context. If omitted, an auto-generated ID with prefix `api_subscriber_` is used.","properties":{"id":{"type":"string","description":"Unique user identifier (required if sender is provided)"},"name":{"type":"string","description":"User display name"},"email":{"type":"string","description":"User email address"}}},"TagOperations":{"type":"object","description":"Add or remove tags on the current session. At least one of `add` or `remove` must be present.","properties":{"add":{"type":"array","items":{"type":"string"},"description":"Tags to add to the session"},"remove":{"type":"array","items":{"type":"string"},"description":"Tags to remove from the session"}}},"RequestOptions":{"type":"object","properties":{"includeMetadata":{"type":"boolean","description":"Include `responsesIds` and `nodesIds` arrays in the result"},"includeStrippedMarkdownTextResponses":{"type":"boolean","description":"Include `responsesStrippedMarkdownText` array with Markdown-stripped plain text"}}},"EventResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"result":{"type":"object","properties":{"responses":{"type":"array","items":{"$ref":"#/components/schemas/AgentResponse"}},"responsesIds":{"type":"array","items":{"type":"string"},"description":"Response IDs (only when `includeMetadata` is true)"},"nodesIds":{"type":"array","items":{"type":"string"},"description":"Flow node IDs that generated responses (only when `includeMetadata` is true)"},"responsesStrippedMarkdownText":{"type":"array","items":{"type":"string"},"description":"Plain text responses without Markdown (only when `includeStrippedMarkdownTextResponses` is true)"}}}}},"AgentResponse":{"type":"object","properties":{"id":{"type":"string","description":"Response ID (e.g. \"TX_<uuid>\")"},"type":{"type":"string","description":"Response type (text, buttons, cards, etc.)"},"options":{"type":"array","items":{"type":"string"},"description":"Response content"},"altText":{"type":"string","description":"Plain-text version of the response"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Error message"}}}}},"paths":{"/api/events":{"post":{"tags":["Events"],"summary":"Send a message to an AI Agent","description":"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.\n\n**Usage flow:**\n1. Trigger the greeting with a postback message (`type: \"node\"`, `data: \"greeting\"`) to start a new session\n2. Send text messages for each conversation turn\n3. Use a consistent `sender.id` to maintain session context across messages","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventRequest"}}}},"responses":{"200":{"description":"Agent response(s) returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Token handle mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```