Guide

Agent API — Atlas for AI agents

The Agent API exposes tool execution endpoints that AI agents use to send WhatsApp messages, search knowledge, and track delivery — all scoped to the agent's granted permissions. It is the simplest path for any external AI runtime to interact with Mirai.

Two APIs, one transport layer

Atlas API

For developer integrations — OAuth apps, service accounts, webhook consumers. Full audit log, run history, and fine-grained scopes.

Base: /v1/atlas

Agent API

For AI agents — tool execution, manifest discovery, knowledge search. Simplified auth model, single scope gates all operations.

Base: /agent/v1

Available tools

send_messageatlas.actions.execute

Reply to a customer in an existing WhatsApp conversation.

POST /agent/v1/tools/send_message
Body: { conversation_id, text, category? }
send_message_to_phoneatlas.actions.execute

Send to any phone number — creates or reuses customer and conversation automatically.

POST /agent/v1/tools/send_message_to_phone
Body: { phone_number, text, template_id?, category? }
search_knowledgeatlas.knowledge.read

Search the shared knowledge base for grounded answers.

GET /agent/v1/knowledge/search?query=...&top_k=5
get_message_statusatlas.actions.execute

Poll delivery status of a sent message by provider_message_id.

GET /agent/v1/tools/messages/:providerMessageId/status
manifestatlas.actions.execute

Discover all tools available to this agent from its granted scopes.

GET /agent/v1/tools/manifest

The 24-hour window

WhatsApp allows free-form messages only within 24 hours of a customer's last message. After that window closes, you must use a pre-approved WhatsApp template.

Window open

Send text freely. No template required.

Window closed

Include template_id and set category to match.

Delivery feedback loop

After sending a message, poll for status or subscribe to the agent.message_delivery webhook event to be notified when the message transitions from sent → delivered → read.

GET /agent/v1/tools/messages/:providerMessageId/status

Response:
{ "ok": true, "data": { "status": "delivered", "updated_at": "..." } }

status: sent | delivered | read | failed

Error handling

UNAUTHORIZED

Check your Bearer token is valid and not expired.

FORBIDDEN

Your API key is missing atlas.actions.execute — ask your administrator to add it.

NOT_FOUND

The conversation_id does not exist or belongs to a different org.

VALIDATION_ERROR

Request body failed validation — check field types and required fields.

CONFLICT

Idempotency key reused with a different payload — use a new key.

Quick start

  1. 1Get an API key with atlas.actions.execute scope from the Developer Console.
  2. 2Call GET /agent/v1/tools/manifest to see which tools are available.
  3. 3Send messages with POST /agent/v1/tools/send_message or POST /agent/v1/tools/send_message_to_phone.
  4. 4Poll GET /agent/v1/tools/messages/:id/status or subscribe to agent.message_delivery webhooks.
Build a sales AI agentFull API reference