ACE SEND API

Quickstart ​

Send your first message through the sandbox in five minutes, then switch to live.

1. Create a test key ​

In the console open Settings → API and webhooks and create a key:

  • Mode: Test. Test keys send through the sandbox: free, nothing reaches a phone.
  • Permissions: Send and Status (the default).

Creating a key needs two-factor authentication on your user. The key is shown once — copy it to your secret store. Below it is ACE_SEND_API_KEY:

bash
export ACE_SEND_API_KEY=ak_test_…

2. Find a template ​

Messages are sent with the templates your team created in the console. List the ones you can send:

bash
curl https://api.ace-send.com/v1/templates \
  -H "Authorization: Bearer $ACE_SEND_API_KEY"
json
{
  "data": [
    {
      "name": "welcome_bonus",
      "version": 3,
      "channel": "whatsapp",
      "category": "marketing",
      "languages": ["pt", "en"],
      "texts": { "pt": "Olá {{name}}! Seu bônus {{promo_code}} já está ativo." },
      "variables": [
        { "key": "name", "example": { "pt": "Ana" }, "fallback": { "pt": "cliente" } },
        { "key": "promo_code", "example": { "pt": "BONUS10" }, "fallback": {} }
      ]
    }
  ]
}

A variable with a fallback in the language may be left out; promo_code has none, so it must be sent.

3. Send a message ​

bash
curl -X POST https://api.ace-send.com/v1/messages \
  -H "Authorization: Bearer $ACE_SEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-1" \
  -d '{
    "to": "+5521998120937",
    "template": "welcome_bonus",
    "language": "pt",
    "variables": { "name": "Ana", "promo_code": "BONUS10" },
    "reference": "crm-42"
  }'

The answer is 202 Accepted with the message:

json
{
  "data": {
    "id": "msg_CgdWeHQN4sPaZnXfh7kP5",
    "status": "queued",
    "to": "+5521998120937",
    "channel": "whatsapp",
    "template": { "name": "welcome_bonus", "version": 3 },
    "text": "Olá Ana! Seu bônus BONUS10 já está ativo.",
    "price": null,
    "test": true,
    "...": "…"
  }
}

reference is your own id: it comes back with the message and its webhooks, and you can search by it. Idempotency-Key makes the request safe to repeat — see Idempotency.

4. Check the status ​

The sandbox plays the statuses of a real provider: sent after a second, delivered after 3, read after 10.

bash
curl https://api.ace-send.com/v1/messages/msg_CgdWeHQN4sPaZnXfh7kP5 \
  -H "Authorization: Bearer $ACE_SEND_API_KEY"

To test failures, send to a number ending in 0000 (no WhatsApp) or 0001 (invalid) — see the sandbox numbers.

5. Get statuses as webhooks ​

Polling works for a test; in production let statuses come to you. In Settings → API and webhooks set a webhook address (HTTPS) and choose the events, for example message.delivered, message.read and message.failed. Every delivery is signed: check the signature before you trust it. Send a test event checks the address.

6. Go live ​

  1. Make sure the balance is topped up (Billing in the console) — live messages are paid.
  2. Create a key with the Live mode and swap it in. Nothing else changes: same URLs, same requests.
  3. Handle the errors that only live sending meets: insufficient_funds, daily_limit_reached.

Test and live keys see only their own messages, so the sandbox history never mixes with real traffic.

ACE SEND API v1

© ACE SEND