---
title: "Send a free form engagement message."
method: POST
path: "/whatsapp/v1/messages/engagement"
tags: ["Messages"]
---

# Send a free form engagement message.

`POST /whatsapp/v1/messages/engagement`

## Request

- Base URL: `https://rest.smsportal.com`
- URL: `https://rest.smsportal.com/whatsapp/v1/messages/engagement`
- Auth: HTTP basic

A free form message can only be sent while the destination number is in the customer service window.

Example request:
            
    POST /whatsapp/v1/messages/engagement
    {
        "businessPhoneNumberId": "841234567890",
        "recipient": "27000000001",
        "content": "Hello World!"
    }

## Request body

- EngagementRequest
  - `businessPhoneNumberId` string, required: The id of the business phone number to send the message from
  - `recipient` string, nullable: This field can contain a phone number or a BSUID.
  - `destinationNumber` string, nullable: This is a legacy field that we are keeping around until all customers have migrated to using the Recipient field. It is recommended to use the Recipient field instead of this one.
  - `customerId` string, nullable: Optional identifier that can be supplied at send time to help customers track their messages
  - `type` string, nullable: WhatsApp supports [address, audio, contacts, document, image, interactive, location, location request, reaction, sticker, template, text and video]. This field specifies what type of message is being sent.
  - `text` string, nullable: The text content of the message. Populated when Type is "text".
  - `image` ImageReference
    - `caption` string, nullable: Optional caption to display beneath the image.
    - `id` string, nullable: The WhatsApp media ID of a previously uploaded image.
    - `url` string, nullable: A publicly accessible URL of the image. Either Id or Url must be provided.
  - `sticker` StickerReference
    - `id` string, nullable: The WhatsApp media ID of a previously uploaded sticker.
    - `url` string, nullable: A publicly accessible URL of the sticker. Either Id or Url must be provided.
  - `video` VideoReference
    - `caption` string, nullable: Optional caption to display beneath the video.
    - `id` string, nullable: The WhatsApp media ID of a previously uploaded video.
    - `url` string, nullable: A publicly accessible URL of the video. Either Id or Url must be provided.
  - `audio` AudioReference
    - `id` string, nullable: The WhatsApp media ID of a previously uploaded audio file.
    - `url` string, nullable: A publicly accessible URL of the audio file. Either Id or Url must be provided.
  - `document` DocumentReference
    - `caption` string, nullable: Optional caption to display beneath the document.
    - `filename` string, nullable: The filename shown to the recipient.
    - `id` string, nullable: The WhatsApp media ID of a previously uploaded document.
    - `url` string, nullable: A publicly accessible URL of the document. Either Id or Url must be provided.
  - `interactive` InteractiveReference
    - `type` string, nullable
    - `bodyText` string, nullable: The main body text of the interactive message.
    - `footerText` string, nullable: Optional footer text displayed below the action.
  - `location` LocationReference
    - `latitude` number, double: The latitude coordinate of a geographic location.
    - `longitude` number, double: The longitude coordinate of a geographic location.
    - `address` string, nullable: The address of a geographic location, typically including street, city, or other identifying details.
    - `name` string, nullable: The name of the location.
  - `contacts` ContactReference[], nullable: Contacts payload. Populated when Type is "contacts".
    - `name` ContactName
      - `formattedName` string, nullable: The full formatted name, e.g. "Mr John Smith Jr."
      - `firstName` string, nullable
      - `lastName` string, nullable
      - `middleName` string, nullable
      - `prefix` string, nullable
      - `suffix` string, nullable
    - `phones` ContactPhone[], nullable: One or more phone numbers for the contact.
      - `phone` string, nullable
      - `type` string, nullable: e.g. CELL, MAIN, IPHONE, HOME, WORK
    - `emails` ContactEmail[], nullable: One or more email addresses for the contact.
      - `email` string, nullable
      - `type` string, nullable: e.g. HOME, WORK
    - `addresses` ContactAddress[], nullable: One or more physical addresses for the contact.
      - `street` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `zip` string, nullable
      - `country` string, nullable
      - `countryCode` string, nullable
      - `type` string, nullable: e.g. HOME, WORK
    - `org` ContactOrg
      - `company` string, nullable
      - `department` string, nullable
      - `title` string, nullable
    - `urls` ContactUrl[], nullable
      - `url` string, nullable
      - `type` string, nullable: HOME or WORK.
    - `birthday` string, nullable
  - `recipientIdentity` RecipientIdentity
    - `recipient` string, nullable
    - `phoneNumber` string, nullable
    - `bsuid` string, nullable
    - `hasPhoneNumber` boolean
    - `hasBsuid` boolean
    - `isSendable` boolean
    - `preferredIdentifier` string, nullable

## Response `200`

The template message was sent successfully

- EngagementResponse
  - `errorCode` string, nullable, required
  - `errorDetail` string, nullable, required
  - `businessPhoneNumberId` string, nullable, required
  - `recipient` string, nullable, required
  - `destinationNumber` string, nullable
  - `customerId` string, nullable, required
  - `messageId` integer, required

## Other responses

- `400`: The template send was invalid, see the ErrorDetail
- `401`: The request was not properly authorized
- `500`: Something unexpected went wrong, please try again

---

[API](https://skmtc.dev/smsportal/apis/smsportal-whatsapp-api.md) - [All operations](https://skmtc.dev/smsportal/apis/smsportal-whatsapp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smsportal/apis/smsportal-whatsapp-api/revisions/d90371930885?raw)