# Send a message through the API

URL: https://aihio.ai/en/help/ai-agent/message-api\
Description: Call an AI agent from your server, continue a conversation and handle API errors.

The message API lets your application send a question to an Aihio AI agent and receive a JSON response. It does not require an embedded chat window.

## Before you start

You need a published agent's ID and an API key from the same workspace. Check API-key availability in your subscription and create a key in the integration settings in Oma Aihio.

> **Warning — Keep the API key on your server:**
>
> Never put the key in browser code, a distributed mobile application, a URL or
> version control. Route application calls through your server and check the
> user's authorization there. Revoke an exposed key and replace it.

## Send your first message

Set `AIHIO_API_KEY` and `AIHIO_AGENT_ID` in your server environment. The first contains the secret API key; the second is the agent's UUID. Run this command on your server or in a secure local terminal:

```sh
curl --fail-with-body https://app.aihio.ai/api/v1/messages \
  -H "x-api-key: ${AIHIO_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data "{\"chatbot_id\":\"${AIHIO_AGENT_ID}\",\"message\":\"Where can I find help using the service?\"}"
```

A successful response includes a `conversation_id` and a `message`. This call consumes service usage; it is not a free connectivity check. Do not repeatedly send the same message just to test connectivity.

## Request fields

The endpoint is `POST /api/v1/messages`. Authenticate with the `x-api-key` header, not a Bearer token.

| Field              | Required | Content                                                                                      |
| ------------------ | -------- | -------------------------------------------------------------------------------------------- |
| `chatbot_id`       | Yes      | UUID of an agent belonging to the API key's workspace.                                       |
| `message`          | Yes      | Message text, 1–10,000 characters.                                                           |
| `conversation_id`  | No       | Conversation ID returned by the previous response.                                           |
| `external_user_id` | No       | Your user ID, at most 255 characters. It does not prove identity on its own.                 |
| `metadata`         | No       | JSON object containing additional data. Do not include secrets or unnecessary personal data. |

## Continue a conversation

Keep the first response's `conversation_id` in your application's user-specific state and include it with the next message. Never share it between users or trust an ID supplied by another user.

```json
{
  "chatbot_id": "00000000-0000-4000-8000-000000000001",
  "message": "Could you explain your previous answer?",
  "conversation_id": "ID_FROM_PREVIOUS_RESPONSE"
}
```

Replace the example UUID with your agent ID and `conversation_id` with the actual response value. Omit the conversation ID to start a new conversation.

## Read the response

| Field             | Use                                                    |
| ----------------- | ------------------------------------------------------ |
| `conversation_id` | Associate the next message with the same conversation. |
| `message`         | The agent's response text.                             |
| `sources`         | Associated source information, when available.         |
| `follow_ups`      | Suggested follow-up questions, when available.         |
| `tokens`          | Token usage information returned with the response.    |
| `timing`          | Optional processing timing information.                |

The endpoint returns a complete JSON response, not a progressively streamed response. Provide waiting and error states in your application. Do not assume every response includes sources or follow-up questions.

## Recover from errors

| HTTP status | Check                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------ |
| `400`       | JSON shape, field names and message length.                                                |
| `401`       | API key, header name and whether the key is still valid.                                   |
| `402`       | Usage and available balance.                                                               |
| `403`       | Model access or the agent's identity requirements.                                         |
| `404`       | Agent ID and membership in the API key's workspace.                                        |
| `422`       | A safety restriction blocked the request; do not automatically vary requests to bypass it. |
| `429`       | Request frequency; slow down and observe the response's rate-limit headers.                |
| `500`       | Service error; provide recovery guidance and retain the request ID for support.            |

A timeout does not prove that a message was not processed. This request has no idempotency key: blindly resending can produce another answer and additional usage. Error bodies can differ, including identity failures, so also handle the HTTP status.

The precise machine-readable description is the [Aihio OpenAPI document](https://app.aihio.ai/api/openapi). This guide covers messaging, not an API for managing agents or knowledge sources.
## Next steps

- [Receive events with webhooks](/en/help/ai-agent/webhooks) — Send agent events to your system and verify incoming webhook requests.