Skip to content
Login
API referenceAPI v1

External APIs

Authenticate, discover templates, and send WhatsApp messages from your own backend.

Base URL and authentication

Your existing AV Bot backend
https://avbot.server.avolvelabs.com/api/v1

Authorization: Bearer YOUR_TENANT_TOKEN
Content-Type: application/json

Every request needs a positive numeric tenantId in the JSON body. The token must belong to that active tenant. Keep it on your integration backend.

You can attach X-Request-ID with a valid UUID to correlate logs. The API returns a request ID in its response headers. It is not an idempotency key.

List templates

POST/api/v1/templates

Read saved templates and their required runtime inputs. Returns only the authenticated tenant’s templates and associated sender numbers.

Body fieldTypeDescription
tenantIdinteger · requiredYour tenant ID; a numeric string is also accepted.
accountIdUUID · optionalFilter by a saved WhatsApp account.
template_namestring · optionalFilter by exact template name.
languagestring · optionalFilter by a language code, such as en_US.
pageinteger · optionalDefault 1. Allowed: 1–10000.
pageSizeinteger · optionalDefault 50. Allowed: 1–100.
Request · cURL
curl --request POST 'https://avbot.server.avolvelabs.com/api/v1/templates' \
  --header 'Authorization: Bearer YOUR_TENANT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"tenantId": 1}'
200 · Example response
{
  "success": true,
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "accountId": "22222222-2222-4222-8222-222222222222",
      "template_name": "order_update",
      "language": "en_US",
      "category": "UTILITY",
      "status": "APPROVED",
      "isActive": true,
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}, order {{2}} is ready."
        }
      ],
      "variableSchema": null,
      "inputs": [
        {
          "key": "body.1",
          "label": "BODY {{1}}",
          "kind": "text"
        },
        {
          "key": "body.2",
          "label": "BODY {{2}}",
          "kind": "text"
        }
      ],
      "senders": [
        {
          "accountId": "22222222-2222-4222-8222-222222222222",
          "numberId": "123456789012345",
          "phoneNumber": "+919000000001"
        }
      ],
      "canSend": true,
      "unsupportedReason": null
    }
  ],
  "page": 1,
  "pageSize": 50,
  "hasMore": false
}

Continue requesting the next page while hasMore is true. An empty result is a successful response with data: []. This endpoint reads local records and does not sync with Meta.

Send a template message

POST/api/v1/messages/template

Send an active, approved template to a recipient. The API validates ownership and inputs, checks the shared rate limiter, saves the message, and calls the provider directly.

Body fieldTypeDescription
tenantIdinteger · requiredThe active tenant that owns your bearer token.
template_namestring · requiredThe saved template’s exact name.
tostring · requiredInternational recipient number with country code. Indian local mobiles are normalized to 91.
languagestring · conditionalRequired when the name has multiple matching languages.
accountIdUUID · conditionalSelect an account when the template name is ambiguous across accounts.
numberIdstring · conditionalMeta phone number ID; required when the chosen account has multiple sender numbers.
parametersobject · conditionalRequired input keys with string or number values. Static templates need none.
Request · cURL
curl --request POST 'https://avbot.server.avolvelabs.com/api/v1/messages/template' \
  --header 'Authorization: Bearer YOUR_TENANT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "tenantId": 1,
  "template_name": "order_update",
  "language": "en_US",
  "to": "+919876543210",
  "parameters": {
    "body.1": "Alex",
    "body.2": "ORD-123"
  }
}'
200 · Provider accepted the message
{
  "success": true,
  "messageId": "33333333-3333-4333-8333-333333333333",
  "providerMessageId": "wamid.EXAMPLE",
  "data": {
    "messages": [
      {
        "id": "wamid.EXAMPLE"
      }
    ]
  }
}

A 200 confirms provider acceptance. Later webhook receipts establish delivery or failure. New recipients are saved as API contacts without automatically granting marketing consent. Blocked contacts are rejected.

See parameter formats and media inputs

Errors and status codes

Errors return a JSON msg describing the problem. Provider-outcome errors also include the saved message ID.

StatusMeaningWhat to do
400Invalid fields, inputs, or pagination.Check the request against the selected template’s inputs.
403Missing/invalid token, tenant mismatch, inactive tenant, or blocked contact.Verify credentials, tenant status, and contact eligibility.
404No matching owned account, sender, or template.Choose identifiers returned for this tenant.
409Ambiguous sender/template or an unapproved/inactive template.Specify account, language, or number; check approval.
429The shared tenant send allowance is exhausted.Wait for Retry-After before retrying.
500Unexpected internal failure.Inspect backend logs using the response request ID.
502Provider rejection or uncertain send outcome.Check the saved message and receipts before sending again.
503Limiter unavailable or missing sender credentials.Restore Redis or configure the selected WhatsApp account.
Example validation error
{
  "msg": "Template must be active and approved before sending"
}

Retries and duplicate sends

The API does not deduplicate requests. Repeating a successful request creates another message. Preserve the returned message ID in your integration.

When you receive 429

Read Retry-After in seconds and wait before retrying. No outgoing message or SQS job is created for that throttled API request. The same 30-per-second tenant allowance is shared with campaigns and chat.

When the provider outcome is uncertain

502 · Investigate before retrying
{
  "msg": "Message outcome is uncertain; check message status before sending again",
  "messageId": "33333333-3333-4333-8333-333333333333",
  "retryable": false
}

A network failure may happen after Meta accepts a message. Use the saved message and later receipts to decide whether another send is appropriate. Do not automatically retry responses with retryable: false.

Understand the shared tenant limit
AV Bot · Developer documentationBuilt for better conversations.