Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt

Use this file to discover all available pages before exploring further.

Send rich media content including images, videos, audio files, documents, stickers, location information, and contact cards.

​
Sending Images

Send Image
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "image",
    "media": {
      "mediaId": "media_abc123",
      "caption": "Check out this image!"
    }
  }'

​
Sending Videos

Send Video
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "video",
    "media": {
      "mediaId": "media_xyz789",
      "caption": "Watch this video"
    }
  }'

​
Sending Audio

Send Audio
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "audio",
    "media": {
      "mediaId": "media_audio456"
    }
  }'
Audio messages do not support captions.

​
Sending Documents

Send Document
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "document",
    "media": {
      "mediaId": "media_doc789",
      "filename": "Monthly_Report.pdf",
      "caption": "Here is your monthly report"
    }
  }'

​
Sending Stickers

Send WebP stickers (static or animated):
Send Sticker
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "sticker",
    "sticker": {
      "mediaId": "media_sticker123"
    }
  }'

​
Sticker Requirements

TypeFormatMax SizeDimensions
StaticWebP100 KB512x512 px
AnimatedWebP500 KB512x512 px
Stickers must be exactly 512x512 pixels in WebP format. Other formats or dimensions will be rejected.

​
Sending Location

Share a location with coordinates:
Send Location
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "location",
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "name": "Chirp HQ",
      "address": "123 Main St, San Francisco, CA"
    }
  }'

​
Location Fields

FieldTypeRequiredDescription
latitudenumberYesLatitude coordinate
longitudenumberYesLongitude coordinate
namestringNoLocation name (shown as title)
addressstringNoFull address (shown below name)

​
Sharing Contacts

Share one or more contacts using the vCard format:
Send Contact
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "contacts",
    "contacts": {
      "contacts": [
        {
          "name": {
            "formattedName": "John Doe",
            "firstName": "John",
            "lastName": "Doe"
          },
          "phones": [
            { "phone": "+15551234567", "type": "CELL" },
            { "phone": "+15559999999", "type": "WORK" }
          ],
          "emails": [
            { "email": "john@example.com", "type": "WORK" }
          ],
          "org": {
            "company": "Acme Inc",
            "title": "Senior Engineer"
          }
        }
      ]
    }
  }'

​
Contact Fields

FieldTypeRequiredDescription
name.formattedNamestringYesFull display name
name.firstNamestringNoFirst name
name.lastNamestringNoLast name
name.middleNamestringNoMiddle name
name.prefixstringNoName prefix (Dr., Mr., etc.)
name.suffixstringNoName suffix (Jr., III, etc.)
phonesarrayNoPhone numbers
emailsarrayNoEmail addresses
addressesarrayNoPhysical addresses
orgobjectNoOrganization information
urlsarrayNoWebsite URLs
birthdaystringNoBirthday (YYYY-MM-DD format)

​
Phone Types

Valid phone types: CELL, MAIN, IPHONE, HOME, WORK

​
Email/Address Types

Valid types: HOME, WORK

​
Uploading Media

Before sending media, you must upload it using the Media API:
Upload Media
curl -X POST https://api.buildwithchirp.com/v1/media \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -F "file=@/path/to/image.jpg"
Upload Response
{
  "id": "media_abc123",
  "mimeType": "image/jpeg",
  "fileSize": 102400
}
Use the returned id as the mediaId when sending messages.

​
Media Requirements

​
Supported Formats

TypeFormatsMax Size
ImageJPEG, PNG5 MB
VideoMP4, 3GPP16 MB
AudioAAC, MP3, OGG, AMR16 MB
DocumentPDF, DOC, DOCX, XLS, XLSX, PPT, PPTX100 MB
StickerWebP100 KB (static), 500 KB (animated)

​
Response

Response
{
  "id": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "from": "+15551234567",
  "to": "+15559876543",
  "type": "image",
  "status": "queued",
  "timestamp": "2024-01-15T12:00:00.000Z"
}