Sending messages

In order to send a WhatsApp message, you must have an active WhatsApp channel and perform a HTTP request to the following endpoint with a valid access key

Send a message

Send a message to a channel

POST/workspaces/{workspaceId}/channels/{channelId}/messages
Authorization
Path parameters
workspaceId*string (uuid)

The ID of the workspace

channelId*string (uuid)

The ID for a channel

Body
senderSender (object)
receiver*Receiver (object)
referenceReference (string)
templatenullable Template (object)
metaMeta (object)
replyToReplyTo (object)
bodyMessageBody
capFrequencyboolean

If set to true, the frequency capping settings of the platform will be used to either allow or reject the message to a contact. Can only be set to true if the message is sent to a contact and .meta.extraInformation.useCase is marketing.

one of
Response

Message was accepted for processing

Body
id*Id-2 (string (uuid))
channelId*ChannelId (string (uuid))
sender*one of
receiver*one of
metaMeta (object)
referenceReference (string)
partsParts (array of object)
status*Status-3 (enum)
acceptedprocessingsentsending_faileddelivereddelivery_faileddeleted
reasonstring
directionDirection (enum)
incomingoutgoing
replyToReplyTo (object)
lastStatusAt*string (date-time)
createdAt*string (date-time)
updatedAt*string (date-time)
detailsstring

This field is used to store additional information related to the message status.

failurenullable Failure (object)
any of
Request
const response = await fetch('/workspaces/{workspaceId}/channels/{channelId}/messages', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "receiver": {
        "contacts": [
          {}
        ]
      }
    }),
});
const data = await response.json();
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "sender": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      }
    }
  },
  "receiver": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      }
    }
  },
  "meta": {
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "source_id": "text",
        "source_url": "text",
        "media_url": "text",
        "tracking_id": "text"
      }
    },
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "price": {
            "currencyCode": "text"
          }
        }
      ]
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "email": {
      "subject": "text"
    }
  },
  "reference": "text",
  "parts": [
    {
      "platformReference": "text"
    }
  ],
  "status": "accepted",
  "reason": "text",
  "direction": "incoming",
  "replyTo": {
    "id": "text",
    "type": "message"
  },
  "lastStatusAt": "2024-04-24T14:45:09.682Z",
  "createdAt": "2024-04-24T14:45:09.682Z",
  "updatedAt": "2024-04-24T14:45:09.682Z",
  "details": "text",
  "failure": {
    "source": {
      "code": "text",
      "name": "text"
    }
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": false
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "https://example.com"
          }
        }
      ],
      "metadata": {
        "subject": "text"
      }
    }
  }
}

When sending outbound messages as well as setting the receiver information you must set message body field in all cases except for sending a message template when you must only set the template field

Body

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "+31612345678"
     }
   ]
 },
 "body": {...}
}

Template

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "+31612345678"
     }
   ]
 },
 "template": {...}
}

If it has been more than 24 hours since a customer last messaged you, you have to start a conversation by sending a template message first. Non-template messages can only be sent when the customer care window is active. You can check the expiry time for an active customer care window for a contact by making a request as follows:

Get channel details for a contact

Retrieve channel information for a given contact.

GET/workspaces/{workspaceId}/channels/{channelId}/contacts/{contactId}
Authorization
Path parameters
workspaceId*string (uuid)

The ID of the workspace

channelId*string (uuid)

The ID for a channel

contactId*string (uuid)

The ID for a contact

Response

OK

Body
serviceWindowExpireAt*nullable string (date-time)
isPermanentSessionnullable boolean
metadatanullable object
Request
const response = await fetch('/workspaces/{workspaceId}/channels/{channelId}/contacts/{contactId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();
Response
{
  "serviceWindowExpireAt": "2024-04-24T14:45:09.682Z",
  "isPermanentSession": false
}

The Channels API supports many of the features of WhatsApp, however due to the omni channel nature of the API there may be some differences between the Channels API message and the native WhatsApp API. Here is an overview of the WhatsApp messages types and Channels API message types:

WhatsApp API typeChannels API

text

image / sticker

audio / document / video

location

reaction

-

interactive - quick reply button

interactive - list

interactive - multi product message

-

interactive - product

-

contacts

-

replies

template

Outbound messages

Except for the template section all examples below must be set in the body field.

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "+31612345678"
     }
   ]
 },
 "body": {...}
}

Text

Text Message

{
  "type": "text",
  "text": {
    "text": "Single text message"
  }
}

Text message with reply buttons

{
  "type": "text",
  "text": {
    "text": "Single text message with reply actions",
    "actions": [
      {
        "type": "reply",
        "reply": {
          "text": "Reply action 1"
        }
      },
      {
        "type": "reply",
        "reply": {
          "text": "Reply action 2"
        }
      }
    ]
  }
}

Text message with postback actions

{
  "type": "text",
  "text": {
    "text": "Single text message with postback actions",
    "actions": [
      {
        "type": "postback",
        "postback": {
          "text": "Postback action 1",
          "payload": "postback-payload-1"
        }
      },
      {
        "type": "postback",
        "postback": {
          "text": "Postback action 2",
          "payload": "postback-payload-2"
        }
      }
    ]
  }
}

Text message with reply and postback actions

{
  "type": "text",
  "text": {
    "text": "Single text message with reply and postback actions",
    "actions": [
      {
        "type": "postback",
        "postback": {
          "text": "Postback action 1",
          "payload": "postback-payload-1"
        }
      },
      {
        "type": "reply",
        "reply": {
          "text": "Reply action 1"
        }
      }
    ]
  }
}

Image

Single image message

{
  "type": "image",
  "image": {
    "images": [
      {
        "altText": "Label of first image",
        "mediaUrl": "https://www.messagebird.com/image.png"
      }
    ]
  }
}

Single image message with text

{
  "type": "image",
  "image": {
    "images": [
      {
        "altText": "Label of first image",
        "mediaUrl": "https://www.messagebird.com/image.png"
      }
    ],
    "text": "Single image message"
  }
}

Multiple image message

{
  "type": "image",
  "image": {
    "images": [
      {
        "altText": "Label of first image",
        "mediaUrl": "https://www.messagebird.com/image1.png"
      },
      {
        "altText": "Label of second image",
        "mediaUrl": "https://www.messagebird.com/image2.png"
      }
    ],
    "text": "Multiple images message"
  }
}

Single image message with postback actions

{"type": "image",
  "image": {
    "images": [
      {
        "altText": "Image label",
        "mediaUrl": "https://www.messagebird.com/image.png"
      }
    ],
    "text": "Single image message with postback actions",
    "actions": [
      {
        "type": "postback",
        "postback": {
          "payload": "postback-payload-1",
          "text": "Postback option 1"
        }
      },
      {
        "postback": {
          "payload": "postback-payload-2",
          "text": "Postback option 2"
        },
        "type": "postback"
      }
    ]
  }
}

Single image message with label and reply actions

{
  "type": "image",
  "image": {
    "text": "Single image message with reply actions",
    "images": [
      {
        "mediaURL": "https://www.messagebird.com/image.png",
        "altText": "Image label"
      }
    ],
    "actions": [
      {
        "type": "reply",
        "reply": {
          "text": "Reply action 1"
        }
      },
      {
        "type": "reply",
        "reply": {
          "text": "Reply action 2"
        }
      }
    ]
  }
}

Single image message with label, postback and reply actions

{
  "type": "image",
  "image": {
    "text": "Single image message with postback and reply actions",
    "images": [
      {
        "mediaURL": "https://www.messagebird.com/image.png",
        "altText": "Image label"
      }
    ],
    "actions": [
      {
        "type": "postback",
        "postback": {
          "text": "Postback action",
          "payload": "postback-payload"
        }
      },
      {
        "type": "reply",
        "reply": {
          "text": "Reply action"
        }
      }
    ]
  }
}

Multiple images message with labels and postback actions

{
  "type": "image",
  "image": {
    "images": [
      {
        "altText": "First image label",
        "mediaUrl": "https://www.messagebird.com/image1.png"
      },
      {
        "altText": "Second image label",
        "mediaUrl": "https://www.messagebird.com/image2.png"
      }
    ],
    "text": "Multiple images message with postback actions",
    "actions": [
      {
        "type": "postback",
        "postback": {
          "payload": "postback-payload-1",
          "text": "Postback action 1"
        }
      },
      {
        "postback": {
          "payload": "postback-payload-2",
          "text": "Postback action 2"
        },
        "type": "postback"
      }
    ]
  }
}

Multiple images message with reply actions

{{
  "type": "image",
  "image": {
    "images": [
      {
        "altText": "First image label",
        "mediaUrl": "https://www.messagebird.com/image1.png"
      },
      {
        "altText": "Second image label",
        "mediaUrl": "https://www.messagebird.com/image2.png"
      }
    ],
    "text": "Multiple images message with reply actions",
    "actions": [
      {
        "type": "reply",
        "reply": {
          "text": "Reply action 1"
        }
      },
      {
        "reply": {
          "text": "Reply action 2"
        },
        "type": "reply"
      }
    ]
  }
}

Multiple images message with labels, postback and reply actions

{{
  "type": "image",
  "image": {
    "images": [
      {
        "altText": "First image label",
        "mediaUrl": "https://www.messagebird.com/image2.png"
      },
      {
        "altText": "Second image label",
        "mediaUrl": "https://www.messagebird.com/image2.png"
      }
    ],
    "text": "Multiple images message with postback and reply actions",
    "actions": [
      {
        "type": "postback",
        "postback": {
          "payload": "postback-payload",
          "text": "Postback action"
        }
      },
      {
        "reply": {
          "text": "Reply action"
        },
        "type": "reply"
      }
    ]
  }
}

File

Single file message

{
  "type": "file",
  "file": {
    "text": "Single file message",
    "files": [
      {
        "contentType": "video/mp4",
        "mediaUrl": "https://www.messagebird.com/videos/video.mp4"
      }
    ]
  }
}

Single file message with postback and reply actions

{
  "type": "file",
  "file": {
    "text": "Single file message",
    "files": [
      {
        "contentType": "video/mp4",
        "mediaUrl": "https://www.messagebird.com/videos/video.mp4"
      }
    ],
    "actions": [
      {
        "type": "postback",
        "postback": {
          "text": "Postback action"
        }
      },
      {
        "type": "reply",
        "reply": {
          "text": "Reply action"
        }
      }
    ]
  }
}

Multiple files message

{
  "type": "file",
  "file": {
    "text": "Multiple files message",
    "files": [
      {
        "contentType": "video/mp4",
        "mediaUrl": "https://www.messagebird.com/videos/video.mp4"
      },
      {
        "contentType": "application/pdf",
        "mediaUrl": "https://www.messagebird.com/documents/file-sample_150kB.pdf"
      }
    ]
  }
}

Multiple files message with filename

{
  "type": "file",
  "file": {
    "text": "Multiple files message",
    "files": [
      {
        "contentType": "video/mp4",
        "mediaUrl": "https://www.messagebird.com/videos/video.mp4"
      },
      {
        "contentType": "application/pdf",
        "mediaUrl": "https://www.messagebird.com/documents/file-sample_150kB.pdf",
        "filename": "passport.pdf"
      }
    ]
  }
}

Multiple files message with two postback actions and a reply action

{
  "type": "file",
  "file": {
    "text": "Multiple files message",
    "files": [
      {
        "contentType": "video/mp4",
        "mediaUrl": "https://www.messagebird.com/videos/video.mp4"
      },
      {
        "contentType": "application/pdf",
        "mediaUrl": "https://www.messagebird.com/documents/file-sample_150kB.pdf",
        "filename": "passport.pdf"
      }
    ],
    "actions": [
      {
        "type": "postback",
        "postback": {
          "text": "Postback action 1",
          "payload": "postback-payload-1"
        }
      },
      {
        "type": "postback",
        "postback": {
          "text": "Postback action 2",
          "payload": "postback-payload-2"
        }
      },
      {
        "type": "reply",
        "reply": {
          "text": "Reply action"
        }
      }
    ]
  }
}

Location

{
 "type": "location",
 "location": {
   "coordinates": {
     "latitude": 52.3435942,
     "longitude": 4.9091077
   },
   "location": {
     "address": "Trompenburgstraat 2C, 1079 TX Amsterdam",
     "label": "MessageBird Amsterdam office"
   }
 }
}

List

List message without sections

{
  "type": "list",
  "list": {
    "items": [
      {
        "actions": [
          {
            "type": "postback",
            "postback": {
              "payload": "postback-action-payload-1",
              "text": "Postback action 1"
            }
          },
          {
            "type": "postback",
            "postback": {
              "payload": "postback-action-payload-2",
              "text": "Postback action 2"
            }
          }
        ]
      }
    ],
    "title": "List title",
    "altText": "List alt text",
    "text": "List text"
  }
}

List message with sections

{
  
  "type": "list",
  "list": {
    "items": [
      {
      "title": "Section 1",
        "actions": [
          {
            "type": "postback",
            "postback": {
              "payload": "postback-action-payload-1",
              "text": "Postback action 1"
            }
          },
          {