API reference

Generated from the API itself, so it cannot fall out of date. Read the quickstart first.

Base URL

URL	Environment
`https://api.waagent.in/v1`	WA AGENT API

Authentication

Your API key, e.g. wa_live_….

Authorization: Bearer wa_live_YOUR_KEY

POST/messages

Send a template message

Sends one WhatsApp template message to one recipient. Returns as soon as Meta accepts it — acceptance is not delivery, so poll GET /messages/{id} or read the DLR report for that.

Parameters

Name	In		Description
`Idempotency-Key`	header	optional	Retrying with the same value returns the original message instead of sending again.

Request body

Field	Type		Description
`messaging_product`	`"whatsapp"`	required
`phone_number_id`	`string`	required	Meta's phone number id for the number you are sending FROM. Shown on the WhatsApp Numbers screen. It must be connected — a number in review or paused is refused.
`to`	`string`	required	The recipient, in E.164 including the leading `+`. The `+` is required: without a country code we would have to guess one, and ten digits is a complete number in several countries. Meta accepts the bare form; we do not, because guessing wrong delivers your message to a stranger. `pattern: ^\+[1-9]\d{6,14}$` Example: `+919876543210`
`type`	`"template"`	required
`template`	`object`	required
`name`	`string`	optional	The template's name at Meta. Requires `language`. Provide this or `id`, not both.
`id`	`string`	optional	The template id from the Templates screen. Unambiguous on its own, so `language` is not needed with it.
`language`	`object`	optional	Required with `name`. Must match the template exactly — `en` and `en_US` are two different templates at Meta.
`code`	`string`	required	Example: `en, en_US`
`variables`	`object<string, string>`	required	Values keyed by slot id — see the variables table above. Every slot the template declares must be filled; a missing one is refused rather than sent blank, because Meta would deliver "Hi , your order shipped" to a real person. Example: `{"body.1":"Arjit","body.2":"SR-4471","button.0.1":"SR-4471"}`
`header_media`	`object`	optional	Your own file for an IMAGE/VIDEO/DOCUMENT header, replacing the one stored with the template, for this message only. Refused on a template with no media header (`HEADER_MEDIA_NOT_APPLICABLE`).
`link`	`string`	required	A public `https` URL. Meta fetches it at send time; a dead or slow link fails the message with Meta's own `meta_code`. `pattern: ^https://`

Example

curl -X POST https://api.waagent.in/v1/messages \
  -H "Authorization: Bearer wa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "phone_number_id": "106540352242922",
  "to": "+919876543210",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": {
      "code": "en"
    },
    "variables": {
      "body.1": "Arjit",
      "button.0.1": "SR-4471"
    }
  }
}'

Responses

Status	Meaning
`200`	Meta accepted the message.
`401`	The API key is missing, malformed, revoked, or suspended.
`402`	The plan quota is used up, or the subscription has lapsed.
`403`	This plan does not include API access.
`404`	No such template, or no stored file for its media header.
`409`	The number or the template cannot send right now.
`422`	The body failed validation, a template variable is missing, or `header_media` was sent for a template with no media header.
`429`	Too many requests on this key. See `Retry-After`.
`502`	Meta refused the message, or the media upload it needed. See `meta_code`.

GET/messages/{id}

Look up a message

The delivery state of one message. Accepts either the wamid a send returned or our own message_id.

Status moves queued → sent → delivered → read, or to failed. It only ever moves forward: a late webhook cannot walk it back.

Parameters

Name	In		Description
`id`	path	required	A `wamid.…` or a `message_id`.

Example

curl -X GET https://api.waagent.in/v1/messages/wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSN0QxRjhCMzk2NkE1RDcyRTVFAA== \
  -H "Authorization: Bearer wa_live_YOUR_KEY"

Responses

Status	Meaning
`200`	The message.
`401`	The API key is missing, malformed, revoked, or suspended.
`403`	This plan does not include API access.
`404`	No message with that id on this account.
`429`	Too many requests on this key.

GET/numbers

List your WhatsApp numbers

Every number on your account, connected or not. phone_number_id is the field POST /messages and GET /numbers itself both key on.

Example

curl -X GET https://api.waagent.in/v1/numbers \
  -H "Authorization: Bearer wa_live_YOUR_KEY"

Responses

Status	Meaning
`200`	Your numbers.
`401`	The API key is missing, malformed, revoked, or suspended.
`403`	This plan does not include API access.
`429`	Too many requests on this key.

GET/templates

List your templates

Your templates with variables and buttons already computed — see "Numbers and templates" above. Unfiltered and unpaged is the common case for a typical WABA's template catalogue.

Parameters

Name	In		Description
`status`	query	optional	Only templates in this status — `APPROVED` for "what can I send".
`waba_id`	query	optional	Only templates on this WABA. From `GET /numbers`' `waba_id`.
`page`	query	optional
`page_size`	query	optional

Example

curl -X GET https://api.waagent.in/v1/templates \
  -H "Authorization: Bearer wa_live_YOUR_KEY"

Responses

Status	Meaning
`200`	Your templates.
`401`	The API key is missing, malformed, revoked, or suspended.
`403`	This plan does not include API access.
`422`	A query parameter failed validation.
`429`	Too many requests on this key.

GET/templates/{id}

Look up a template

One template, by our own id (the id field GET /templates returns).

Parameters

Name	In		Description
`id`	path	required

Example

curl -X GET https://api.waagent.in/v1/templates/{id} \
  -H "Authorization: Bearer wa_live_YOUR_KEY"

Responses

Status	Meaning
`200`	The template.
`401`	The API key is missing, malformed, revoked, or suspended.
`403`	This plan does not include API access.
`404`	No template with that id on this account.
`429`	Too many requests on this key.

POST/leads

Create a lead from your website's form

For website integrations only. Authenticate with a lead key, never an API key — a lead key (wa_lead_…) can only ever create a lead, so it is safe to use from a browser or a form-builder tool, unlike your messaging API key. Create one under Developer → Website Leads in the customer portal.

The contact lands in your Contacts with source website. The response never says whether the contact was new or already existed, by design.

Request body

Field	Type		Description
`name`	`string`	required
`phone`	`string`	required	Loosely accepted here and normalised on our side; an unusable number comes back as a 422 your form can show the visitor. Example: `9876543210`

Example

curl -X POST https://api.waagent.in/v1/leads \
  -H "Authorization: Bearer wa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Arjit",
  "phone": "9876543210"
}'

Responses

Status	Meaning
`202`	Accepted. Deliberately generic — the same body whether this created a new contact or matched one you already had.
`401`	The lead key is missing, malformed, revoked, or suspended.
`403`	This key's origin allow-list does not include the caller.
`422`	The body failed validation, or the phone is unusable.
`429`	Too many requests on this key, or from this IP.

GET/openapi.jsonNo auth required

This document

The machine-readable spec. Import the URL into Postman or Insomnia.

Example

curl -X GET https://api.waagent.in/v1/openapi.json \
  -H "Authorization: Bearer wa_live_YOUR_KEY"

Responses

Status	Meaning
`200`	The OpenAPI document.

URL

Environment

https://api.waagent.in/v1

WA AGENT API

Name

Description

Idempotency-Key

header

optional

Retrying with the same value returns the original message instead of sending again.

Field

Type

Description

messaging_product

"whatsapp"

required

phone_number_id

string

required

Meta's phone number id for the number you are sending FROM. Shown on the WhatsApp Numbers screen. It must be connected — a number in review or paused is refused.

to

string

required

The recipient, in E.164 including the leading `+`. The + is required: without a country code we would have to guess one, and ten digits is a complete number in several countries. Meta accepts the bare form; we do not, because guessing wrong delivers your message to a stranger.

pattern: ^\+[1-9]\d{6,14}$

Example: +919876543210

type

"template"

required

template

object

required

name

string

optional

The template's name at Meta. Requires language. Provide this or id, not both.

id

string

optional

The template id from the Templates screen. Unambiguous on its own, so language is not needed with it.

language

object

optional

Required with name. Must match the template exactly — en and en_US are two different templates at Meta.

code

string

required

Example: en, en_US

variables

object<string, string>

required

Values keyed by slot id — see the variables table above. Every slot the template declares must be filled; a missing one is refused rather than sent blank, because Meta would deliver "Hi , your order shipped" to a real person.

Example: {"body.1":"Arjit","body.2":"SR-4471","button.0.1":"SR-4471"}

header_media

object

optional

Your own file for an IMAGE/VIDEO/DOCUMENT header, replacing the one stored with the template, for this message only. Refused on a template with no media header (HEADER_MEDIA_NOT_APPLICABLE).

link

string

required

A public https URL. Meta fetches it at send time; a dead or slow link fails the message with Meta's own meta_code.

pattern: ^https://

curl -X POST https://api.waagent.in/v1/messages \ -H "Authorization: Bearer wa_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "phone_number_id": "106540352242922", "to": "+919876543210", "type": "template", "template": { "name": "order_shipped", "language": { "code": "en" }, "variables": { "body.1": "Arjit", "button.0.1": "SR-4471" } } }'

Status

Meaning

200

Meta accepted the message.

401

The API key is missing, malformed, revoked, or suspended.

402

The plan quota is used up, or the subscription has lapsed.

403

This plan does not include API access.

404

No such template, or no stored file for its media header.

409

The number or the template cannot send right now.

422

The body failed validation, a template variable is missing, or `header_media` was sent for a template with no media header.

429

Too many requests on this key. See `Retry-After`.

502

Meta refused the message, or the media upload it needed. See `meta_code`.

Name

Description

id

path

required

A wamid.… or a message_id.

Status

Meaning

200

The message.

401

The API key is missing, malformed, revoked, or suspended.

403

This plan does not include API access.

404

No message with that id on this account.

429

Too many requests on this key.

Status

Meaning

200

Your numbers.

401

The API key is missing, malformed, revoked, or suspended.

403

This plan does not include API access.

429

Too many requests on this key.

Name

Description

status

query

optional

Only templates in this status — APPROVED for "what can I send".

waba_id

query

optional

Only templates on this WABA. From GET /numbers' waba_id.

page

query

optional

page_size

query

optional

Status

Meaning

200

Your templates.

401

The API key is missing, malformed, revoked, or suspended.

403

This plan does not include API access.

422

A query parameter failed validation.

429

Too many requests on this key.

Name

Description

id

path

required

Status

Meaning

200

The template.

401

The API key is missing, malformed, revoked, or suspended.

403

This plan does not include API access.

404

No template with that id on this account.

429

Too many requests on this key.

Field

Type

Description

name

string

required

phone

string

required

Loosely accepted here and normalised on our side; an unusable number comes back as a 422 your form can show the visitor.

Example: 9876543210

Status

Meaning

202

Accepted. Deliberately generic — the same body whether this created a new contact or matched one you already had.

401

The lead key is missing, malformed, revoked, or suspended.

403

This key's origin allow-list does not include the caller.

422

The body failed validation, or the phone is unusable.

429

Too many requests on this key, or from this IP.

Status

Meaning

200

The OpenAPI document.