Media Messages

Convers8 allows you to send various types of media messages to your WhatsApp contacts, including images, audio, video, and documents. This guide covers how to use the media messaging API.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://waba-v1.convers8.africa

Media Types

Convers8 supports the following media types:

• Images: JPG, PNG, and other image formats
• Audio: MP3, OGG, and other audio formats
• Video: MP4 and other video formats
• Documents: PDF, DOC, DOCX, and other document formats

Sending Image Messages

Endpoint

POST /whatsapp/message/image

Request Body

Property	Type	Description
to	string	The recipient's phone number in international format
name	string	The recipient's name
content	object	An object containing the message content
content.url	string	The URL of the image to send
content.caption	string	(Optional) A caption for the image

Example Request

{
  "to": "+1234567890",
  "name": "Customer Name",
  "content": {
    "url": "https://example.com/image.jpg",
    "caption": "Check out this image!"
  }
}

cURL Example

curl --request POST \
     --url https://waba-v1.convers8.africa/whatsapp/message/image \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+1234567890",
       "name": "Customer Name",
       "content": {
         "url": "https://example.com/image.jpg",
         "caption": "Check out this image!"
       }
     }'

Sending Audio Messages

Endpoint

POST /whatsapp/message/audio

Request Body

Property	Type	Description
to	string	The recipient's phone number in international format
name	string	The recipient's name
content	object	An object containing the message content
content.url	string	The URL of the audio file to send

Example Request

{
  "to": "+1234567890",
  "name": "Customer Name",
  "content": {
    "url": "https://example.com/audio.mp3"
  }
}

cURL Example

curl --request POST \
     --url https://waba-v1.convers8.africa/whatsapp/message/audio \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+1234567890",
       "name": "Customer Name",
       "content": {
         "url": "https://example.com/audio.mp3"
       }
     }'

Sending Video Messages

Endpoint

POST /whatsapp/message/video

Request Body

Property	Type	Description
to	string	The recipient's phone number in international format
name	string	The recipient's name
content	object	An object containing the message content
content.url	string	The URL of the video file to send
content.caption	string	(Optional) A caption for the video

Example Request

{
  "to": "+1234567890",
  "name": "Customer Name",
  "content": {
    "url": "https://example.com/video.mp4",
    "caption": "Check out this video!"
  }
}

cURL Example

curl --request POST \
     --url https://waba-v1.convers8.africa/whatsapp/message/video \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+1234567890",
       "name": "Customer Name",
       "content": {
         "url": "https://example.com/video.mp4",
         "caption": "Check out this video!"
       }
     }'

Sending Document Messages

Endpoint

POST /whatsapp/message/document

Request Body

Property	Type	Description
to	string	The recipient's phone number in international format
name	string	The recipient's name
content	object	An object containing the message content
content.url	string	The URL of the document to send
content.filename	string	(Optional) The filename to display

Example Request

{
  "to": "+1234567890",
  "name": "Customer Name",
  "content": {
    "url": "https://example.com/document.pdf",
    "filename": "Important Document.pdf"
  }
}

cURL Example

curl --request POST \
     --url https://waba-v1.convers8.africa/whatsapp/message/document \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+1234567890",
       "name": "Customer Name",
       "content": {
         "url": "https://example.com/document.pdf",
         "filename": "Important Document.pdf"
       }
     }'

Response Format

All API endpoints return a JSON response with the following structure:

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "messageId": "wamid.abcdefghijklmnopqrstuvwxyz"
  }
}

Error Handling

In case of an error, the response will look like:

{
  "success": false,
  "message": "Error message",
  "error": {
    "code": "error_code",
    "details": "Error details"
  }
}

Common error codes include:

• invalid_parameter: One or more parameters in the request are invalid
• unauthorized: Invalid or missing API key
• rate_limit_exceeded: Too many requests in a short period
• media_download_failed: The media file could not be downloaded
• media_invalid: The media file is invalid or unsupported

Media Size Limits

WhatsApp imposes the following size limits for media files:

• Images: 5MB
• Audio: 16MB
• Video: 16MB
• Documents: 100MB

Best Practices

1. Media Hosting: Ensure your media files are hosted on a reliable server with good uptime.
2. File Size: Keep media files within WhatsApp's size limits.
3. File Format: Use common file formats that are widely supported.
4. Error Handling: Implement proper error handling to manage failed media deliveries.
5. Rate Limiting: Be mindful of WhatsApp's rate limits to avoid being blocked.