WhatsApp - seven.io API

Use this API to send WhatsApp messages via the WhatsApp Business API (WABA). You can send template messages, freetext messages, media (image, video, audio, document, sticker), locations, contacts, and interactive messages. Reactions are sent via the events endpoint.

To use this endpoint, your API key must have the waba scope enabled. You also need a registered WhatsApp Business sender number.

POST/api/waba/messages

Send message

Send a WhatsApp message to a recipient. You can send template messages, freetext messages, media (image, video, audio, document, sticker), locations, contacts, and interactive messages (buttons, lists).

Required parameters

Name
from
Type
string
Description
Your registered WhatsApp Business sender number in international format (e.g. 4915112345678).
Name
to
Type
string
Description
Recipient phone number in international format (e.g. 4917612345678).

Template message parameters

Name
type
Type
string
Description
Set to template for sending a pre-approved WhatsApp template message.
Name
template
Type
string
Description
The name of the approved WhatsApp template (e.g. hello_world).
Name
language
Type
string
Description
Language code of the template (e.g. de, en).
Name
components
Type
object
Optional
Optional
Description
Template parameter values. Contains optional arrays for header, body, and buttons. Values are positional and replace {{1}}, {{2}}, etc. in the template.

components

object

Template component parameters

Name
header
Type
array
Optional
Optional
Description
Values for header placeholders. For text headers, provide strings. For image headers, provide a URL.
Name
body
Type
array
Optional
Optional
Description
Values for body placeholders. Each entry replaces the corresponding {{n}} variable.
Name
buttons
Type
array
Optional
Optional
Description
Button parameter values. Each entry is an object with type, sub_type, and parameters.

Freetext message parameters

Name
type
Type
string
Description
Set to text or omit. The message text is sent within a 24-hour conversation window.
Name
text
Type
string
Description
The message text. Can only be sent within an active 24-hour conversation window.

Image message parameters

Name
type
Type
string
Description
Set to image.
Name
url
Type
string
Description
Public URL of the image file (JPEG, PNG).
Name
caption
Type
string
Optional
Optional
Description
Optional caption for the image.

Video message parameters

Name
type
Type
string
Description
Set to video.
Name
url
Type
string
Description
Public URL of the video file (MP4, 3GPP).
Name
caption
Type
string
Optional
Optional
Description
Optional caption for the video.

Audio message parameters

Name
type
Type
string
Description
Set to audio.
Name
url
Type
string
Description
Public URL of the audio file (MP3, OGG, AMR, AAC).

Document message parameters

Name
type
Type
string
Description
Set to document.
Name
url
Type
string
Description
Public URL of the document file (PDF, DOC, etc.).
Name
filename
Type
string
Description
The filename shown to the recipient.
Name
caption
Type
string
Optional
Optional
Description
Optional caption for the document.

Sticker message parameters

Name
type
Type
string
Description
Set to sticker.
Name
url
Type
string
Description
Public URL of the sticker file (WebP). Static stickers: 512x512px, max 100KB. Animated stickers: 512x512px, max 500KB.

Location message parameters

Name
type
Type
string
Description
Set to location.
Name
latitude
Type
number
Description
Latitude of the location.
Name
longitude
Type
number
Description
Longitude of the location.
Name
name
Type
string
Optional
Optional
Description
Name of the location.
Name
address
Type
string
Optional
Optional
Description
Address of the location.

Contacts message parameters

Name
type
Type
string
Description
Set to contacts.
Name
contacts
Type
array
Description
Array of contact objects. Each contact must have a name object (with first_name and optional last_name) and a phones array (each with phone and optional type: cell, main, iphone, home, work).

Interactive button message parameters

Name
type
Type
string
Description
Set to interactive.
Name
interactive_type
Type
string
Description
Set to button.
Name
body
Type
string
Description
Body text displayed to the user.
Name
buttons
Type
array
Description
Array of 2-3 button objects, each with id (unique identifier) and title (display text, max 20 characters).
Name
header
Type
string
Optional
Optional
Description
Optional header text.
Name
footer
Type
string
Optional
Optional
Description
Optional footer text.

Interactive list message parameters

Name
type
Type
string
Description
Set to interactive.
Name
interactive_type
Type
string
Description
Set to list.
Name
body
Type
string
Description
Body text displayed to the user.
Name
button_text
Type
string
Description
Text shown on the list button.
Name
sections
Type
array
Description
Array of section objects, each with title and rows (array of row objects with id, title, and optional description).
Name
header
Type
string
Optional
Optional
Description
Optional header text.
Name
footer
Type
string
Optional
Optional
Description
Optional footer text.

Optional parameters

Name
delay
Type
timestamp
Optional
Optional
Description
Date/time for scheduled sending. Format: YYYY-MM-DD hh:mm:ss or Unix timestamp.
Name
ttl
Type
integer
Optional
Optional
Description
Specifies the validity period of the message in minutes. The default is 2880, i.e. 48 hours.
Name
label
Type
string
Optional
Optional
Description
Custom label for statistics. Max. 100 characters, allowed characters: a-z, A-Z, 0-9, .-_@.
Name
performance_tracking
Type
boolean
Optional
Optional
Description
Activate click and performance tracking for URLs found in the message text. This also activates the URL shortener.
Name
foreign_id
Type
string
Optional
Optional
Description
Your own ID for this message. Returned in status report callbacks. Max. 64 characters, allowed characters: a-z, A-Z, 0-9, .-_@.

Template message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "template",
      "template": "hello_world",
      "language": "de"
    }'

Response

{
    "success": "100",
    "total_price": 0.0735,
    "balance": 123.45,
    "debug": "false",
    "sms_type": "WA",
    "messages": [
        {
            "id": "12345678",
            "sender": "4915112345678",
            "recipient": "4917612345678",
            "text": "{\"type\":\"template\",\"template\":\"hello_world\",\"language\":\"de\",\"rendered\":{\"body\":\"Hallo Welt!\"}}",
            "encoding": "gsm",
            "label": null,
            "parts": 1,
            "udh": null,
            "is_binary": false,
            "price": 0.0735,
            "channel": "WA",
            "success": true,
            "error": null,
            "error_text": null
        }
    ]
}

Template with parameters

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "template",
      "template": "order_confirmation",
      "language": "de",
      "components": {
        "body": ["Max Mustermann", "ORD-12345"],
        "buttons": [
          {
            "type": "button",
            "sub_type": "url",
            "parameters": [{"type": "text", "text": "ORD-12345"}]
          }
        ]
      }
    }'

Freetext message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "text": "Thanks for your message, we will take care of it!"
    }'

Image message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "image",
      "url": "https://example.com/photo.jpg",
      "caption": "Check out this image!"
    }'

Video message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "video",
      "url": "https://example.com/video.mp4",
      "caption": "Watch this video"
    }'

Audio message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "audio",
      "url": "https://example.com/audio.mp3"
    }'

Document message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "document",
      "url": "https://example.com/invoice.pdf",
      "filename": "invoice.pdf",
      "caption": "Your invoice"
    }'

Sticker message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "sticker",
      "url": "https://example.com/sticker.webp"
    }'

Location message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "location",
      "latitude": 48.8566,
      "longitude": 2.3522,
      "name": "Eiffel Tower",
      "address": "5 Avenue Anatole France, 75007 Paris"
    }'

Contacts message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "contacts",
      "contacts": [
        {
          "name": {"first_name": "John", "last_name": "Doe"},
          "phones": [{"phone": "+491234567890", "type": "cell"}]
        }
      ]
    }'

Interactive button message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "interactive",
      "interactive_type": "button",
      "body": "How can we help you?",
      "header": "Support",
      "footer": "Tap a button to choose",
      "buttons": [
        {"id": "btn_sales", "title": "Sales"},
        {"id": "btn_support", "title": "Support"},
        {"id": "btn_other", "title": "Other"}
      ]
    }'

Interactive list message

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "interactive",
      "interactive_type": "list",
      "header": "Our Products",
      "body": "Browse our product categories:",
      "footer": "Select an option",
      "button_text": "View Options",
      "sections": [
        {
          "title": "Electronics",
          "rows": [
            {"id": "phone_1", "title": "Smartphones", "description": "Latest models"},
            {"id": "laptop_1", "title": "Laptops", "description": "Business & Gaming"}
          ]
        }
      ]
    }'

Template components

The components structure supports three optional arrays: header, body, and buttons. Values are positional and replace {{1}}, {{2}}, etc. in the template.

Header parameters

Text header: Provide string values for text placeholders
Image header: Provide a URL to the image

Body parameters

Provide string values that replace {{1}}, {{2}}, etc. in the template body.

Button parameters

For URL buttons with dynamic suffixes, provide an array of button objects:

Name
type
Type
string
Description
Always button.
Name
sub_type
Type
string
Description
The button type, e.g. url.
Name
parameters
Type
array
Description
Array of parameter objects with type and text properties.

Header + Body + Buttons

{
    "from": "4915112345678",
    "to": "4917612345678",
    "type": "template",
    "template": "appointment_reminder",
    "language": "de",
    "components": {
        "header": ["Appointment confirmation"],
        "body": ["Max Mustermann", "2026-02-15", "2:00 PM", "Dr. Smith"],
        "buttons": [
            {
                "type": "button",
                "sub_type": "url",
                "parameters": [{"type": "text", "text": "abc123"}]
            }
        ]
    }
}

Image header + Body

{
    "from": "4915112345678",
    "to": "4917612345678",
    "type": "template",
    "template": "product_available",
    "language": "de",
    "components": {
        "header": ["https://example.com/product.jpg"],
        "body": ["Premium Widget"]
    }
}

DELETE/api/waba/messages/{id}

Delete message

Delete a scheduled WhatsApp message before it has been sent.

Name
id
Type
string
Description
The ID of the message to delete. Passed as a URL path parameter.

Already sent messages cannot be deleted. WhatsApp does not support message revocation.

Request

DELETE

/api/waba/messages/{id}

curl -X DELETE https://gateway.seven.io/api/waba/messages/12345678 \
    -H "X-Api-Key: YOUR_API_KEY"

Response (success)

{
    "success": true
}

Response (already sent)

{
    "error_code": 400,
    "error_message": "Message already sent. WhatsApp does not support message revocation."
}

Response (not found)

{
    "code": 404,
    "message": "Page not found",
    "errors": []
}

POST/api/waba/events

Send event

Send conversation events such as read receipts, typing indicators, or reactions to a WhatsApp contact.

Events can only be sent for messages from the last 7 days. Older conversations are no longer eligible for event delivery.

At least one of to or msg_id must be provided to identify the target conversation or message.

Read/Typing event parameters

Name
from
Type
string
Description
Your registered WhatsApp Business sender number.
Name
to
Type
string
Optional
Optional
Description
Recipient phone number in international format. At least one of to or msg_id must be provided.
Name
event
Type
string
Description
The event type. Available values: read, is_typing.
Name
msg_id
Type
string
Optional
Optional
Description
Explicit message ID to mark as read. At least one of to or msg_id must be provided.

Reaction event parameters

Name
event
Type
string
Description
Set to reaction.
Name
msg_id
Type
string
Description
The WhatsApp message ID of the message to react to.
Name
emoji
Type
string
Description
The emoji to use as reaction (e.g. 👍). Send an empty string to remove the reaction.

Read receipt

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "event": "read"
    }'

Typing indicator

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "event": "is_typing"
    }'

Reaction

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "event": "reaction",
      "msg_id": "123456789",
      "emoji": "👍"
    }'

Response

{
    "success": true
}

Error response

{
    "success": false,
    "error_code": 400,
    "error_message": "Invalid WhatsApp sender number"
}

Error responses

Name
100
Description
Message has been accepted by the gateway and is being sent.
Name
7002001
Description
Not in conversation. Freetext messages can only be sent within an active 24-hour conversation window. Use a template message to initiate a conversation.
Name
400
Description
Bad request. Can indicate an invalid sender number, invalid recipient number, or other validation errors.
Name
404
Description
Message not found. The specified message ID does not exist or does not belong to your account.
Name
900
Description
Authentication has failed. Please check the API key used in Authentication.
Name
902
Description
The API key does not have access rights to this endpoint. Ensure the waba scope is enabled.