Messages

Every request sends x-api-key. New here? Start with the quickstart, or read API keys.

OperationSDK callEndpoint
Send a messagemessages.sendPOST /v1/messages/
Get a messagemessages.getGET /v1/messages/{id}

Send a message

Send a WhatsApp message to a phone number. A template message may be sent at any time; text and media only within 24 hours of the recipient's last inbound message, which is WhatsApp's rule rather than ours. The sender is the number this key was issued against. Pass variables to fill a template's placeholders for this send. A test key runs the whole path without delivering anything and returns testMode: true.

Text

await msg.messages.send({
  type: "text",
  to: "+919812345678",
  text: "Your order has shipped.",
});

Template

await msg.messages.send({
  type: "template",
  to: "+919812345678",
  templateId: "tpl_3b9f1c2d4e5a6b7c8d9e0f1a2b3c4d5e",
  variables: {
    "1": "Asha",
    "2": "ORD-4471",
  },
});

Media

await msg.messages.send({
  type: "media",
  to: "+919812345678",
  mediaId: "med_7c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
});

Body

FieldTypeRequiredDescription
tostringyesThe recipient's phone number in E.164 format.
typetemplate | text | mediayestext only works inside the 24-hour window. template works any time but must be approved by Meta. media sends a file you uploaded first.
textstringnoThe message body. Required when type is text.
templateIdstringnoFrom GET /v1/templates. Required when type is template.
variablesobjectnoTemplate placeholder values, keyed by name or index. Omit one and the template's own example value is sent instead. Template messages only.
mediaIdstringnoFrom POST /v1/media/. Required when type is media.
captionstringnoText shown with the file. Media messages only.
replyTostringnoA msg_ id or a WhatsApp id to quote, threading this as a reply.

Response 201

Example response
{
  "id": "msg_7726793e1a4b4c8d9e0f1a2b3c4d5e6f",
  "status": "accepted",
  "type": "template"
}
FieldTypeDescription
idstringPass this to GET /v1/messages/\{id\} for delivery status.
statusaccepted | sent | delivered | read | failedaccepted means we have it, not that it arrived. It moves to sent, delivered and read as WhatsApp reports back, or to failed.
tostringThe recipient, echoed back.
typetemplate | text | mediaThe kind of message that was sent.
whatsappMessageIdstringMeta's own id, for correlating in WhatsApp Manager. Null on a test key.
errorobjectNull unless status is failed.
error.codestringMeta's error code.
error.messagestringMeta's reason for the failure.
createdAtstring (ISO 8601)When we accepted the message.
testModetruePresent and true on a test key. Nothing reached WhatsApp.

Errors

Returns 400, 401, 403, 404, 409, 429, 502, 503. Every one carries the standard envelope — branch on code, not the status. See Errors.

Get a message

Fetch a message's delivery status. accepted means we hold it and Meta has not confirmed yet; sent, delivered and read track WhatsApp's own receipts; failed carries the reason in error. Covers any message in the account, including ones sent from the dashboard.

await msg.messages.get("msg_7726793e1a4b4c8d9e0f1a2b3c4d5e6f");

Path parameters

FieldTypeRequiredDescription
idstringyesThe msg_ id returned by POST /v1/messages.

Response 200

Example response
{
  "id": "msg_7726793e1a4b4c8d9e0f1a2b3c4d5e6f",
  "status": "accepted",
  "type": "template"
}
FieldTypeDescription
idstringPass this to GET /v1/messages/\{id\} for delivery status.
statusaccepted | sent | delivered | read | failedaccepted means we have it, not that it arrived. It moves to sent, delivered and read as WhatsApp reports back, or to failed.
tostringThe recipient, echoed back.
typetemplate | text | mediaThe kind of message that was sent.
whatsappMessageIdstringMeta's own id, for correlating in WhatsApp Manager. Null on a test key.
errorobjectNull unless status is failed.
error.codestringMeta's error code.
error.messagestringMeta's reason for the failure.
createdAtstring (ISO 8601)When we accepted the message.
testModetruePresent and true on a test key. Nothing reached WhatsApp.

Errors

Returns 400, 401, 403, 404, 429, 503. Every one carries the standard envelope — branch on code, not the status. See Errors.