Skip to main content
POST
/
v1
/
whatsapp
/
messages
cURL
curl --request POST \
  --url https://api.buildwithchirp.com/v1/whatsapp/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "+15551234567",
  "to": "+15559876543",
  "type": "text",
  "text": {
    "body": "Hello from Chirp!"
  },
  "media": {
    "mediaId": "media_abc123",
    "caption": "Check out this image!",
    "filename": "document.pdf"
  },
  "sticker": {
    "mediaId": "media_sticker123"
  },
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "Chirp HQ",
    "address": "123 Main St, San Francisco, CA"
  },
  "contacts": {
    "contacts": [
      {
        "name": {
          "formattedName": "John Doe",
          "firstName": "John",
          "lastName": "Doe",
          "middleName": "Robert",
          "prefix": "Dr.",
          "suffix": "Jr."
        },
        "phones": [
          {
            "phone": "+15551234567",
            "type": "CELL"
          }
        ],
        "emails": [
          {
            "email": "[email protected]",
            "type": "WORK"
          }
        ],
        "addresses": [
          {
            "street": "123 Main St",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "United States",
            "countryCode": "US",
            "type": "WORK"
          }
        ],
        "org": {
          "company": "Acme Inc",
          "department": "Engineering",
          "title": "Senior Engineer"
        },
        "urls": [
          {
            "url": "https://example.com",
            "type": "WORK"
          }
        ],
        "birthday": "1990-01-15"
      }
    ]
  },
  "reaction": {
    "messageId": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
    "emoji": "👍"
  },
  "template": {
    "name": "hello_world",
    "language": "en_US",
    "variables": {
      "1": "John",
      "2": "your order"
    }
  },
  "interactive": {
    "type": "buttons",
    "body": "Please choose an option:",
    "header": {
      "type": "text",
      "text": "Welcome!",
      "mediaId": "media_abc123"
    },
    "footer": "Powered by Chirp",
    "buttons": [
      {
        "id": "btn_1",
        "title": "Option 1"
      }
    ],
    "buttonText": "View Options",
    "sections": [
      {
        "rows": [
          {
            "id": "row_1",
            "title": "Item 1",
            "description": "Description of item 1"
          }
        ],
        "title": "Section 1"
      }
    ],
    "url": "https://example.com/checkout",
    "flowId": "1234567890",
    "flowToken": "flow_token_abc123",
    "flowAction": "navigate",
    "flowActionPayload": {
      "screen": "WELCOME",
      "data": {
        "user_name": "John"
      }
    }
  },
  "replyTo": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI"
}
'
{
  "id": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "from": "<string>",
  "to": "<string>",
  "type": "text",
  "status": "queued",
  "timestamp": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

App API key (format: sk_live_app_* or sk_test_app_*) for app-level operations

Body

application/json
​
from
string
required

WhatsApp phone number to send from (must be assigned to your app)

Example:

"+15551234567"

​
to
string
required

WhatsApp phone number to send to

Example:

"+15559876543"

​
type
enum<string>
required

Type of message to send

Available options:
text,
image,
video,
audio,
document,
sticker,
location,
contacts,
reaction,
template,
interactive
Example:

"text"

​
text
object

Text message content. Required when type is 'text'

​
media
object

Media content. Required when type is 'image', 'video', 'audio', or 'document'. Media must be uploaded first via POST /v1/media.

​
sticker
object

Sticker content. Required when type is 'sticker'. Stickers must be uploaded first via POST /v1/media.

​
location
object

Location content. Required when type is 'location'

​
contacts
object

Contacts content. Required when type is 'contacts'

​
reaction
object

Reaction content. Required when type is 'reaction'. Reacts to an existing message with an emoji.

​
template
object

Template content. Required when type is 'template'

​
interactive
object

Interactive message content. Required when type is 'interactive'

​
replyTo
string

Chirp message ID (msg_wa_) to reply to. Creates a contextual reply that displays the original message. Meta IDs (wamid.) are not accepted.

Minimum string length: 1
Example:

"msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

Response

Message queued successfully

​
id
string
required

Unique identifier for a WhatsApp Message. Format: msg_wa_[test_]{ksuid}

Example:

"msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

​
from
string
required
​
to
string
required
​
type
enum<string>
required
Available options:
text,
image,
video,
audio,
document,
sticker,
location,
contacts,
reaction,
template,
interactive
​
status
enum<string>
required
Available options:
queued
​
timestamp
string<date-time>
required