Sending Media Messages

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

Type	Format	Max Size	Dimensions
Static	WebP	100 KB	512x512 px
Animated	WebP	500 KB	512x512 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

Field	Type	Required	Description
`latitude`	number	Yes	Latitude coordinate
`longitude`	number	Yes	Longitude coordinate
`name`	string	No	Location name (shown as title)
`address`	string	No	Full address (shown below name)

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

Field	Type	Required	Description
`name.formattedName`	string	Yes	Full display name
`name.firstName`	string	No	First name
`name.lastName`	string	No	Last name
`name.middleName`	string	No	Middle name
`name.prefix`	string	No	Name prefix (Dr., Mr., etc.)
`name.suffix`	string	No	Name suffix (Jr., III, etc.)
`phones`	array	No	Phone numbers
`emails`	array	No	Email addresses
`addresses`	array	No	Physical addresses
`org`	object	No	Organization information
`urls`	array	No	Website URLs
`birthday`	string	No	Birthday (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

Type	Formats	Max Size
Image	JPEG, PNG	5 MB
Video	MP4, 3GPP	16 MB
Audio	AAC, MP3, OGG, AMR	16 MB
Document	PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX	100 MB
Sticker	WebP	100 KB (static), 500 KB (animated)

Response

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

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Sending Media Messages

Sending Images

Sending Videos

Sending Audio

Sending Documents

Sending Stickers

Sticker Requirements

Sending Location

Location Fields

Contact Fields

Phone Types

Email/Address Types

Uploading Media

Media Requirements

Supported Formats

Response

​Sending Images

​Sending Videos

​Sending Audio

​Sending Documents

​Sending Stickers

​Sticker Requirements

​Sending Location

​Location Fields

​Sharing Contacts

​Contact Fields

​Phone Types

​Email/Address Types

​Uploading Media

​Media Requirements

​Supported Formats

​Response

Sending Images

Sending Videos

Sending Audio

Sending Documents

Sending Stickers

Sticker Requirements

Sending Location

Location Fields

Sharing Contacts

Contact Fields

Phone Types

Email/Address Types

Uploading Media

Media Requirements

Supported Formats

Response