Chat API

Quickstart

Four steps to get the bot replying from your own system.

1. 1

   Enable Chat API

   From the panel: Connections → Chat via API. Click Create endpoint.

2. 2

   Save your secret

   The modal shows your endpoint_id and secret. The secret is shown only once. If you lose it you'll have to rotate.

3. 3

   Send a signed message

   From your backend, sign the body with HMAC SHA-256 using your secret. Never expose the secret on the client — server-side code only.

   cURLNode.jsPythonPHP

   Copiar

   # Replace YOUR_ENDPOINT_ID and YOUR_SECRET with the values from your panel
   ENDPOINT="cae_xxxxxxxxxxxxxxxxxxxxxxxxxx"
   SECRET="aakey_live_xxxxxxxxxxxxxxxxxxxxxxxxxx"
   
   BODY='{"visitor_id":"user_42","message":"Hi, are you open?"}'
   SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
   
   curl -X POST "https://autoasistente.com/api/v1/chat-api/$ENDPOINT/messages" \
     -H "Content-Type: application/json" \
     -H "X-AA-Signature: sha256=$SIG" \
     -d "$BODY"

4. 4

   Receive the agent's reply

   The bot's response comes back in the same HTTP response (sync). In case of timeout or human handover, you'll get status:"queued" and need to poll.

   HTTP 200 · status: repliedCopy

   {
     "success": true,
     "status": "replied",
     "conversation_id": "12345",
     "message_id": "67890",
     "reply": {
       "id": "67891",
       "role": "assistant",
       "content": "Yes! We're open 9am to 6pm. How can I help?"
     }
   }

Authentication

Every request carries an HMAC-SHA256 signature of the body in the X-AA-Signature header. This prevents body tampering in transit and proves to the server that the caller holds the secret.

Header format

X-AA-Signature: sha256=<64-hex-chars>

How to compute the signature

1. Serialize the body to a JSON string.
2. Compute HMAC-SHA256(secret, body) in hex.
3. Prefix with sha256= and send as a header.

For GET requests

GET has no body. Sign an empty string:

SIG=$(printf '' | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

Rate limits

Default 60 requests per minute per endpoint, sliding window. Response headers:

If you need a higher limit contact support for your business. Each endpoint has its own bucket — multiple endpoints from the same business don't share quota.

Errors

Error responses use standard HTTP status codes plus a JSON body with consistent structure:

{
  "success": false,
  "error": {
    "code": "SIGNATURE_INVALID",
    "message": "Invalid HMAC signature"
  }
}

Error codes

Send message

Send a user message to the AI agent and wait synchronously for the reply. If the agent responds within 15s, you get the reply in the same HTTP request. If it's in human handover or timeout, you get status:"queued" and must poll.

Path parameters

Body parameters

Headers

Response examples

{
  "success": true,
  "status": "replied",
  "conversation_id": "12345",
  "message_id": "67890",
  "reply": {
    "id": "67891",
    "role": "assistant",
    "content": "Yes! We're open 9am to 6pm. How can I help?"
  }
}

{
  "success": true,
  "status": "queued",
  "conversation_id": "12345",
  "message_id": "67890",
  "message": "Message received. A human agent will reply shortly. Poll GET /messages/poll."
}

Poll messages

When the bot is in human handover or the synchronous response timed out, poll this endpoint to receive new messages from a cursor. Every agent reply (bot or human) shows up here.

Query parameters

Example

# The body of a signed GET is an empty string
SIG=$(printf '' | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl "https://autoasistente.com/api/v1/chat-api/$ENDPOINT/messages/poll?visitor_id=user_42&since=0" \
  -H "X-AA-Signature: sha256=$SIG"

Response

{
  "success": true,
  "messages": [
    {
      "id": "67892",
      "role": "agent",
      "content": "Hi, I'm Maria from the support team.",
      "created_at": "2026-05-15T19:42:11.000Z"
    }
  ],
  "next_cursor": "67892"
}

Health check

Public no-auth endpoint to check service availability (useful for uptime monitors).

{"ok":true,"service":"chat-api"}

Human handover

The bot can escalate to a human when:

• It detects urgency (words like "emergency", "urgent").
• The visitor explicitly asks to "talk to a person".
• The business operator takes over the conversation from the panel.

When this happens:

1. Your next POST /messages gets status:"queued".
2. Your system should start polling /messages/poll every 3s.
3. Human replies arrive with role:"agent" or role:"admin".
4. When the human closes the conversation, it returns to bot mode automatically on the next message.

Idempotency

For safe retries on timeout or network error, include the header X-AA-Idempotency-Key with a unique UUID v4 per logical request.

If we receive the same key within 24h, we return the cached response without re-processing the message. Recommended in any production integration.

curl -X POST "https://autoasistente.com/api/v1/chat-api/$ENDPOINT/messages" \
  -H "X-AA-Signature: sha256=$SIG" \
  -H "X-AA-Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Best practices