WhatsApp Free Form API · Termii Developers

The WhatsApp Free Form API allows businesses to send personalised WhatsApp messages to customers without using pre-approved message templates. Free Form messages can be sent within the 24-hour customer service window, which starts when a customer sends a message to the business. Once the 24-hour window expires, businesses must use a WhatsApp-approved template message to initiate or continue the conversation.

Send Free Form Text Message

This endpoint enables you to send a free-form WhatsApp text message to a customer without using a pre-approved WhatsApp template.

Free-form text messages can be sent only within the 24-hour customer service window, which begins when a customer sends a message to your business. After the 24-hour window expires, you must use an approved WhatsApp template to send a message.

POST https://BASE_URL/api/whatsapp/freeform

Options	Required	Description
phone_number	yes	string The destination phone number. The phone number must be in international format (`Example: 2341065250111`).
device_id	yes	string The Device ID associated with your WhatsApp account. It can be alphanumeric and can be found on the WhatsApp ID page on your Termii Dashboard.
content	yes	string The text message you want to send to the customer. The content can include supported WhatsApp text formatting and URLs.
preview_url	no	boolean Determines whether a preview should be displayed for URLs included in the message. Set to `true` to enable URL previews or `false` to disable them.
api_key	yes	string Your API key. It can be found on your Termii Dashboard.

{
  "device_id": "019f3ce8-5052-7598-ac80-1efc149f3c72",
  "phone_number": "+23470652508111",
  "content": "Hello *Queen Tobi* ~please find attached~ the link https://termii.com/",
  "preview_url": true,
  "api_key": "Your API Key"
}

Sample Response - 200 OK

{
    "code": "ok",
    "balance": 0,
    "message_id": "sig_10f42835de4a40bfa2dd406327bf2c89",
    "message": "Successfully Sent",
    "user": "Termii",
    "message_id_str": "sig_10f42835de4a40bfa2dd406327bf2c89"
}

Send Free Form Image Message

This endpoint enables you to send a free-form WhatsApp image message to a customer. You can include an optional caption with the image.

Free-form image messages can be sent only within the 24-hour customer service window, which begins when a customer sends a message to your business. After the 24-hour window expires, you must use an approved WhatsApp template to initiate or continue the conversation.

POST https://BASE_URL/api/whatsapp/freeform

Options	Required	Description
phone_number	yes	string The destination phone number. The phone number must be in international format (`Example: 2341065250111`).
device_id	yes	string The Device ID associated with your WhatsApp account. It can be alphanumeric and can be found on the WhatsApp ID page on your Termii Dashboard.
type	yes	string Specifies the type of free-form message being sent. For this endpoint, the value must be `image`.
media_url	yes	string The publicly accessible URL of the image you want to send.
caption	no	string The text caption to accompany the image.
api_key	yes	string Your API key. It can be found on your Termii Dashboard.

{
  "device_id": "019f3ce8-5052-7598-ac80-1efc149f3c72",
  "phone_number": "+2347065250817",
  "type": "image",
  "media_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSGpKoT-TSnfaC4SLZ-J65AQnXOt8R2PDnx3OhfZAXbvyGP0QfxhJ04W89O&s=10",
  "caption": "This month's offer",
  "api_key": "Your API Key"
}

Sample Response - 200 OK

{
    "code": "ok",
    "balance": 0,
    "message_id": "sig_57c15abc9ee848e2a05b85e68c7ef746",
    "message": "Successfully Sent",
    "user": "Termii",
    "message_id_str": "sig_57c15abc9ee848e2a05b85e68c7ef746"
}

Send Free Form Document Message

This endpoint enables you to send a free-form WhatsApp document message to a customer. You can optionally include a caption and specify the document's filename.

Free-form document messages can be sent only within the 24-hour customer service window, which begins when a customer sends a message to your business. After the 24-hour window expires, you must use an approved WhatsApp template to initiate or continue the conversation.

POST https://BASE_URL/api/whatsapp/freeform

Options	Required	Description
phone_number	yes	string The destination phone number. The phone number must be in international format (`Example: 2341065250111`).
device_id	yes	string The Device ID associated with your WhatsApp account. It can be alphanumeric and can be found on the WhatsApp ID page on your Termii Dashboard.
type	yes	string Specifies the type of free-form message being sent. For this endpoint, the value must be `document`.
media_url	yes	string The publicly accessible URL of the document you want to send.
caption	no	string The text caption to accompany the document.
filename	no	string The name that will be displayed for the document when the recipient receives it.
api_key	yes	string Your API key. It can be found on your Termii Dashboard.

{
  "device_id": "019f3ce8-5052-7598-ac80-1efc149f3c72",
  "phone_number": "2347065250817",
  "type": "document",
  "media_url": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf",
  "caption": "Your invoice for August",
  "filename": "INV-4821.pdf",
  "api_key": "Your API Key"
}

Sample Response - 200 OK

{
    "code": "ok",
    "balance": 0,
    "message_id": "sig_7203413044cf40b987deea3d8a2208a7",
    "message": "Successfully Sent",
    "user": "Termii",
    "message_id_str": "sig_7203413044cf40b987deea3d8a2208a7"
}

Send Free Form Location Message

This endpoint enables you to send a free-form WhatsApp location message to a customer. The message includes the geographic coordinates of a location and can optionally include a name and address to help identify the location.

Free-form location messages can be sent only within the 24-hour customer service window, which begins when a customer sends a message to your business. After the 24-hour window expires, you must use an approved WhatsApp template to initiate or continue the conversation.

POST https://BASE_URL/api/whatsapp/freeform

Options	Required	Description
phone_number	yes	string The destination phone number. The phone number must be in international format (`Example: 2341065250111`).
device_id	yes	string The Device ID associated with your WhatsApp account. It can be alphanumeric and can be found on the WhatsApp ID page on your Termii Dashboard.
type	yes	string Specifies the type of free-form message being sent. For this endpoint, the value must be `location`.
latitude	yes	number The latitude coordinate of the location.
longitude	yes	number The longitude coordinate of the location.
name	no	string The name of the location displayed to the recipient.
address	no	string The address or additional location details displayed to the recipient.
api_key	yes	string Your API key. It can be found on your Termii Dashboard.

{
  "device_id": "019f3ce8-5052-7598-ac80-1efc149f3c72",
  "phone_number": "2347065250817",
  "type": "location",
  "latitude": 6.5244,
  "longitude": 3.3792,
  "name": "Termii HQ",
  "address": "Yaba, Lagos",
  "api_key": "Your API Key"
}

Sample Response - 200 OK

{
    "code": "ok",
    "balance": 0,
    "message_id": "sig_e9aa19c694a44494b76612d4a0355a64",
    "message": "Successfully Sent",
    "user": "Termii",
    "message_id_str": "sig_e9aa19c694a44494b76612d4a0355a64"
}

Send Free Form Contact Message

This endpoint enables you to send contact information through WhatsApp. You can share one or more contacts, including their name, phone number, email address, and organisation details.

Free-form contact messages can be sent only within the 24-hour customer service window, which begins when a customer sends a message to your business. After the 24-hour window expires, you must use an approved WhatsApp template to initiate or continue the conversation.

POST https://BASE_URL/api/whatsapp/freeform

Options	Required	Description
phone_number	yes	string The destination phone number. The phone number must be in international format (`Example: 2341065250111`).
device_id	yes	string The Device ID associated with your WhatsApp account. It can be alphanumeric and can be found on the WhatsApp ID page on your Termii Dashboard.
type	yes	string Specifies the type of free-form message being sent. For this endpoint, the value must be `contacts`.
contacts	yes	array An array containing the contact information to be shared with the recipient.
contacts[].formattedName	yes	string The full name of the contact as it should be displayed to the recipient.
contacts[].firstName	no	string The first name of the contact.
contacts[].lastName	no	string The last name of the contact.
contacts[].phones	no	array Contains the contact's phone number(s), phone type, and WhatsApp ID where applicable.
contacts[].phones[].phone	yes, if `phones` is provided	string The contact's phone number.
contacts[].phones[].type	no	string The type of phone number, such as `WORK`.
contacts[].phones[].waId	no	string The WhatsApp ID associated with the contact's phone number.
contacts[].emails	no	array Contains the contact's email address(es) and email type.
contacts[].emails[].email	yes, if `emails` is provided	string The contact's email address.
contacts[].emails[].type	no	string The type of email address, such as `WORK`.
contacts[].org	no	object Contains the contact's organisation details.
contacts[].org.company	no	string The company or organisation associated with the contact.
contacts[].org.department	no	string The department within the organisation.
contacts[].org.title	no	string The contact's job title or role.
api_key	yes	string Your API key. It can be found on your Termii Dashboard.

{
  "device_id": "019f3ce8-5052-7598-ac80-1efc149f3c72",
  "phone_number": "2347065250817",
  "type": "contacts",
  "contacts": [
    {
      "formattedName": "Ada Lovelace",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "phones": [
        { "phone": "+2348011111111", "type": "WORK", "waId": "2348011111111" }
      ],
      "emails": [
        { "email": "ada@example.com", "type": "WORK" }
      ],
      "org": { "company": "Termii", "department": "Support", "title": "Agent" }
    }
  ],
  "api_key": "Your API Key"
}

Sample Response - 200 OK

{
    "code": "ok",
    "balance": 0,
    "message_id": "sig_a9b1f2586187411395abd2ec884f13a8",
    "message": "Successfully Sent",
    "user": "Termii",
    "message_id_str": "sig_a9b1f2586187411395abd2ec884f13a8"
}

Send Free Form Interactive Message – Buttons

This endpoint enables you to send a free-form WhatsApp interactive message with buttons. Interactive button messages allow businesses to present customers with predefined actions they can select directly from the WhatsApp conversation.

Free-form interactive messages can be sent only within the 24-hour customer service window, which begins when a customer sends a message to your business. After the 24-hour window expires, you must use an approved WhatsApp template to initiate or continue the conversation.

POST https://BASE_URL/api/whatsapp/freeform

Options	Required	Description
phone_number	yes	string The destination phone number. The phone number must be in international format (`Example: 2341065250111`).
device_id	yes	string The Device ID associated with your WhatsApp account. It can be alphanumeric and can be found on the WhatsApp ID page on your Termii Dashboard.
type	yes	string Specifies the type of free-form message being sent. For this endpoint, the value must be `interactive`.
interactive_type	yes	string Specifies the type of interactive message. For this endpoint, the value must be `button`.
header_text	no	string The text displayed in the header of the interactive message.
body_text	yes	string The main message content displayed to the customer.
footer_text	no	string The text displayed in the footer of the interactive message.
buttons	yes	array An array containing the interactive buttons presented to the customer.
buttons[].id	yes	string A unique identifier for the button. This value is returned when the customer selects the button and can be used to identify the selected action.
buttons[].title	yes	string The text displayed on the button.
api_key	yes	string Your API key. It can be found on your Termii Dashboard.

{
  "device_id": "019f3ce8-5052-7598-ac80-1efc149f3c72",
  "phone_number": "2347065250817",
  "type": "interactive",
  "interactive_type": "button",
  "header_text": "Order #4821",
  "body_text": "Your order is ready. Confirm delivery for tomorrow?",
  "footer_text": "Reply anytime",
  "buttons": [
    { "id": "confirm", "title": "Confirm" },
    { "id": "reschedule", "title": "Reschedule" }
  ],
  "api_key": "Your API Key"
}

Sample Response - 200 OK

{
    "code": "ok",
    "balance": 0,
    "message_id": "sig_c233e3629502488597085e06f29b4d8a",
    "message": "Successfully Sent",
    "user": "Termii",
    "message_id_str": "sig_c233e3629502488597085e06f29b4d8a"
}

Send Free Form Interactive Message – List

This endpoint enables you to send a free-form WhatsApp interactive list message to a customer. List messages allow businesses to present customers with multiple options grouped into sections, which the customer can select directly from the WhatsApp conversation.

POST https://BASE_URL/api/whatsapp/freeform

Options	Required	Description
phone_number	yes	string The destination phone number. The phone number must be in international format (`Example: 2341065250111`).
device_id	yes	string The Device ID associated with your WhatsApp account. It can be alphanumeric and can be found on the WhatsApp ID page on your Termii Dashboard.
type	yes	string Specifies the type of free-form message being sent. For this endpoint, the value must be `interactive`.
interactive_type	yes	string Specifies the type of interactive message. For this endpoint, the value must be `list`.
body_text	yes	string The main message content displayed to the customer.
button_text	yes	string The text displayed on the button that the customer selects to open the list of available options.
footer_text	no	string The text displayed in the footer of the interactive message.
sections	yes	array An array containing the sections used to organise the list options.
sections[].title	yes	string The title of the list section.
sections[].rows	yes	array An array containing the options available within the section.
sections[].rows[].id	yes	string A unique identifier for the list option. This value is used to identify the option selected by the customer.
sections[].rows[].title	yes	string The name of the option displayed to the customer.
sections[].rows[].description	no	string Additional information displayed alongside the list option.
api_key	yes	string Your API key. It can be found on your Termii Dashboard.

{
  "device_id": "019f3ce8-5052-7598-ac80-1efc149f3c72",
  "phone_number": "2347065250817",
  "type": "interactive",
  "interactive_type": "list",
  "body_text": "Pick a delivery window.",
  "button_text": "View slots",
  "sections": [
    {
      "title": "Tomorrow",
      "rows": [
        { "id": "am", "title": "9am – 12pm", "description": "Morning window" },
        { "id": "pm", "title": "1pm – 5pm", "description": "Afternoon window" }
      ]
    }
  ],
  "api_key": "Your API Key"
}

Sample Response - 200 OK

{
    "code": "ok",
    "balance": 0,
    "message_id": "sig_7fc1e1aa4f3542e49d986834a7cf75e6",
    "message": "Successfully Sent",
    "user": "Termii",
    "message_id_str": "sig_7fc1e1aa4f3542e49d986834a7cf75e6"
}