WhatsApp messaging is a powerful part of Our Voice — it allows you to connect with your contacts through WhatsApp using sessions linked to your account. On this page, we'll dive into the different endpoints you can use to manage WhatsApp sessions and messages programmatically. We'll look at how to create sessions, send messages of different types, and track delivery.

Sessions

A WhatsApp session represents a WhatsApp account connected to your Our Voice account via QR code. A session must be connected before you can send messages through it.

Properties

Name
id
Type
string
Description
The ID (uuid) of the session.
Name
account_id
Type
string
Description
Unique identifier for the account this session belongs to.
Name
session_id
Type
string
Description
Internal identifier used by the WhatsApp gateway (e.g. session_uuid).
Name
phone_number
Type
string
Description
The phone number associated with the connected WhatsApp account.
Name
display_name
Type
string
Description
The display name of the WhatsApp account.
Name
status
Type
enum
Description
The status of the session. Types: pending, connected, disconnected, banned, failed.
Name
reason
Type
string
Description
Reason for failure or disconnection, if applicable.
Name
last_seen_at
Type
timestamp
Description
Timestamp of the last activity on this session.
Name
created_at
Type
timestamp
Description
Timestamp of when the session was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the session was last updated.

GET/v1/whatsapp/sessions

List all sessions

This endpoint allows you to display a listing of all WhatsApp sessions linked to your account.

Request

GET

/v1/whatsapp/sessions

curl --request GET \
  --get "https://api.getourvoice.com/v1/whatsapp/sessions" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

POST/v1/whatsapp/sessions

Create a new session

This endpoint allows you to create a new WhatsApp session. After creation, a QR code is returned which must be scanned with a WhatsApp-linked phone to connect the session.

No body parameters are required — the session ID is generated automatically.

Request

POST

/v1/whatsapp/sessions

curl --request POST \
  "https://api.getourvoice.com/v1/whatsapp/sessions" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Response (201)

{
  "success": true,
  "session": {
    "id": "a3f1b2c4-1234-4abc-9def-000011112222",
    "account_id": "43c98bbc-2f78-466b-9b94-b154a1b380ec",
    "session_id": "session_a3f1b2c4-1234-4abc-9def-000011112222",
    "phone_number": null,
    "display_name": "session_a3f1b2c4-1234-4abc-9def-000011112222",
    "status": "pending",
    "last_seen_at": "2024-01-15T10:30:00.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  },
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANS..."
}

GET/v1/whatsapp/sessions/{id}

Display a specified session

This endpoint allows you to display a specified WhatsApp session.

Parameters

Name
id
Type
string
Description
The ID (uuid) of the session.

Request

GET

/v1/whatsapp/sessions/{id}

curl --request GET \
  "https://api.getourvoice.com/v1/whatsapp/sessions/a3f1b2c4-1234-4abc-9def-000011112222" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

GET/v1/whatsapp/sessions/{id}/qr-code

Get the QR code of a session

This endpoint returns the current QR code for a session. The QR code must be scanned with WhatsApp to connect the session. It is only available when the session is in pending status.

Parameters

Name
id
Type
string
Description
The ID (uuid) of the session.

Request

GET

/v1/whatsapp/sessions/{id}/qr-code

curl --request GET \
  "https://api.getourvoice.com/v1/whatsapp/sessions/a3f1b2c4-1234-4abc-9def-000011112222/qr-code" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Response (200)

{
  "success": true,
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANS..."
}

PATCH/v1/whatsapp/sessions/{id}/disconnect

Disconnect a session

This endpoint allows you to disconnect a connected WhatsApp session. The session will be set to disconnected status but will not be deleted.

Parameters

Name
id
Type
string
Description
The ID (uuid) of the session.

Request

PATCH

/v1/whatsapp/sessions/{id}/disconnect

curl --request PATCH \
  "https://api.getourvoice.com/v1/whatsapp/sessions/a3f1b2c4-1234-4abc-9def-000011112222/disconnect" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

PATCH/v1/whatsapp/sessions/{id}/reconnect

Reconnect a session

This endpoint allows you to reconnect a disconnected WhatsApp session.

Parameters

Name
id
Type
string
Description
The ID (uuid) of the session.

Request

PATCH

/v1/whatsapp/sessions/{id}/reconnect

curl --request PATCH \
  "https://api.getourvoice.com/v1/whatsapp/sessions/a3f1b2c4-1234-4abc-9def-000011112222/reconnect" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

DELETE/v1/whatsapp/sessions/{id}

Delete a session

This endpoint allows you to permanently delete a WhatsApp session.

Parameters

Name
id
Type
string
Description
The ID (uuid) of the session.

Request

DELETE

/v1/whatsapp/sessions/{id}

curl --request DELETE \
  "https://api.getourvoice.com/v1/whatsapp/sessions/a3f1b2c4-1234-4abc-9def-000011112222" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Messages

A WhatsApp message is sent through a connected session. Messages can carry different types of content: text, image, video, audio, or document.

Properties

Name
id
Type
string
Description
The ID (uuid) of the message.
Name
whatsapp_session_id
Type
string
Description
Unique identifier of the WhatsApp session used to send this message.
Name
campaign_id
Type
string
Description
Unique identifier of the campaign this message belongs to. Present when message is sent from a campaign.
Name
otp_id
Type
string
Description
Unique identifier of the OTP request this message belongs to. Present when message is sent as OTP from an app.
Name
provider_message_id
Type
string
Description
The message ID returned by the WhatsApp gateway after sending.
Name
from_number
Type
string
Description
The phone number that sent the message.
Name
to_number
Type
array
Description
The phone numbers that received the message (array of phone numbers).
Name
type
Type
enum
Description
The type of message content. Types: text, image, video, audio, document.
Name
content
Type
string
Description
The text content of the message. Required for text type, optional as caption for media types.
Name
media_url
Type
string
Description
URL of the media file. Required for image, video, audio, and document types.
Name
status
Type
enum
Description
The status of the message. Types: queued, sent, delivered, read, failed, scheduled.
Name
direction
Type
enum
Description
The direction of the message: incoming or outgoing.
Name
reason
Type
string
Description
The failure reason if the message status is failed.
Name
cost
Type
double
Description
The cost of the message.
Name
sent_at
Type
timestamp
Description
Timestamp of when the message was sent.
Name
delivered_at
Type
timestamp
Description
Timestamp of when the message was delivered.
Name
read_at
Type
timestamp
Description
Timestamp of when the message was read by the recipient.
Name
metadata
Type
object
Description
Additional metadata attached to the message (webhook events, retry info, etc).
Name
created_at
Type
timestamp
Description
Timestamp of when the message was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the message was last updated.

GET/v1/whatsapp/messages

List all messages

This endpoint allows you to display a listing of all WhatsApp messages for your account. You can filter results by various criteria.

Available filters

Name
filter[to_number]
Type
array
Description
Filter by recipient phone numbers (array).
Name
filter[from_number]
Type
string
Description
Filter by sender phone number.
Name
filter[status]
Type
string
Description
Filter by message status.
Name
filter[direction]
Type
string
Description
Filter by direction: incoming or outgoing.
Name
filter[type]
Type
string
Description
Filter by message type.
Name
session_id
Type
string
Description
Filter by session ID (uuid or session_id string).
Name
time_from
Type
string
Description
Start of the time range filter (ISO 8601 datetime).
Name
time_to
Type
string
Description
End of the time range filter (ISO 8601 datetime).
Name
limit
Type
integer
Description
Number of results per page. Default: 10.

Request

GET

/v1/whatsapp/messages

curl --request GET \
  --get "https://api.getourvoice.com/v1/whatsapp/messages?filter[status]=delivered&filter[direction]=outgoing&limit=10" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

GET/v1/whatsapp/messages/{session_id}/session

List messages for a session

This endpoint allows you to display all WhatsApp messages belonging to a specific session. Supports the same filters as the main messages endpoint.

Parameters

Name
session_id
Type
string
Description
The ID (uuid) or session_id string of the session.

Request

GET

/v1/whatsapp/messages/{session_id}/session

curl --request GET \
  --get "https://api.getourvoice.com/v1/whatsapp/messages/a3f1b2c4-1234-4abc-9def-000011112222/session" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

POST/v1/whatsapp/messages

Send a new message

This endpoint allows you to send a WhatsApp message through a connected session. You can send to one or multiple recipients at once.

The session referenced by whatsapp_session_id must be in connected status.

Required attributes

Name
whatsapp_session_id
Type
string
Description
The ID (uuid) of the connected WhatsApp session to send from.
Name
to_number
Type
array
Description
An array of recipient phone numbers in international format (e.g. ["22996XXXXXX"]).
Name
type
Type
enum
Description
Type of message to send: text, image, video, audio, or document.

Conditional attributes

Name
content
Type
string
Description
The text body of the message. Required when type is text. Optional caption for image, video, and document types.
Name
media_url
Type
string
Description
A publicly accessible URL to the media file. Required when type is image, video, audio, or document.
Name
delay_between
Type
integer
Description
Delay in milliseconds between messages when sending to multiple recipients. Default: 500.

Request

POST

/v1/whatsapp/messages

curl --request POST \
  "https://api.getourvoice.com/v1/whatsapp/messages" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"whatsapp_session_id\": \"a3f1b2c4-1234-4abc-9def-000011112222\",
    \"to_number\": [\"22996XXXXXX\"],
    \"type\": \"text\",
    \"content\": \"Hello from Our Voice!\"
}"

Response (201) — text

{
  "success": true,
  "message": "Message queued for sending",
  "data": {
    "messages": [
      {
        "id": "7f9e1234-abcd-4ef0-8765-aabbccddeeff",
        "whatsapp_session_id": "a3f1b2c4-1234-4abc-9def-000011112222",
        "campaign_id": "1498e4ff-3d09-4dba-bb7c-62851729f7ea",
        "from_number": "22997000000",
        "to_number": "22996XXXXXX",
        "type": "text",
        "content": "Hello from Our Voice!",
        "media_url": null,
        "status": "queued",
        "direction": "outgoing",
        "cost": 10,
        "sent_at": null,
        "delivered_at": null,
        "read_at": null,
        "created_at": "2024-01-15T10:45:00.000000Z",
        "updated_at": "2024-01-15T10:45:00.000000Z"
      }
    ],
    "count": 1,
    "total_cost": 10,
    "new_balance": 4990,
    "remaining_messages": 499
  }
}

Example — send an image

{
  "whatsapp_session_id": "a3f1b2c4-1234-4abc-9def-000011112222",
  "to_number": ["22996XXXXXX", "22961XXXXXX"],
  "type": "image",
  "media_url": "https://example.com/image.jpg",
  "content": "Check out this photo!",
  "delay_between": 1000
}

GET/v1/whatsapp/messages/{id}

Display a specified message

This endpoint allows you to display a specified WhatsApp message.

Parameters

Name
id
Type
string
Description
The ID (uuid) of the message.

Request

GET

/v1/whatsapp/messages/{id}

curl --request GET \
  "https://api.getourvoice.com/v1/whatsapp/messages/7f9e1234-abcd-4ef0-8765-aabbccddeeff" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"