V1 - Broadcast Messages

Send messages to multiple contacts on channels connected to CosmoBots

This document is intended to be used for developers using CosmoBots API to send messages to multiple contacts on channels connected to CosmoBots.

Remember that to send messages to these channels we are considering you already have connected the channel to your Bot on CosmoBots.

Endpoint

POST https://api.cosmobots.io/messages/v1/broadcast

Authentication

• Login into the platform

• Choose the Bot

• On the left sidebar menu, choose Integrations, then API

• Choose the Broadcast Messages API

• Click on Enable API

• Now you can copy channelId and token to use on the requests

Every request needs to have these two parameters on the header. You may retrieve both on the Integration section of the platform. Follow these steps:

Header	Type	Description
channel_id	String	Required. ID of the Channel that will receive the messages
token	String	Required. Token exclusive to the Bot, to be used on this API.

Broadcasting Messages

Here are the body fields used during this request. The format is JSON.

Field	type	Description
message	Object	Required. Information about the content of the message
contact	Array [Objects]	Required. Information about the contacts that will receive the messages.

Message Object

Field	Type	Description
type	String	Required. Types of Message. Options are: Text Buttons Cards Media
template_id	String	ID of the Template being used to send the message
language_code	String	Code for the language of the message. Ex.: "pt_BR"
params	Array [Strings]	When using Templates the values in this array represent the parameters values on messages for all contacts
data	Object	Required. Data related to the content of the message

Message > Data (If Type is Text)

Field	Type	Description
text	String	Text of the message

Message > Data (If Type is Buttons)

Field	Type	Description
title	String	Required. Text of the Button (Caption)
type	String	Required. Type of Button, having the value related to the field payload. Options are: Text Url Payload
value	String	Required. Data related to the payload when the button is clicked

Message > Data (If Type is Cards)

Field	Type	Description
title	String	Required. Title of the Card
subtitle	String	Subtitle of the Card
image_url	String	Image Url of the Card
buttons	Array [Object]	List of Buttons

Message > Data (If Type is Media)

Field	Type	Description
type	String	Required. Type of media. Options are: Image Audio Video Document
url	String	Required. Url of the Media
caption	String	Caption of the Media

Contacts Array [Object]

Field	Type	Description
id	String	Required. ID of the Contact. When the channel is WhatsApp, the id is equivalent to the phone number (complete format).
params	Array [Strings]	When using Templates the values in this array represent the parameters values on the template message for each contact.
context	Object	Custom Data related to the message, that can be used by the Bot during conversation.

Response Async

Field	Type	Description
status	String	Status of the Message Sent Error
broadcast_id	String	ID of the Broadcast

Examples Of Request

Sending Text

POST https://api.cosmobots.io/messages/v1/broadcast

{
   "message": {
      "type": "text",
      "template_id": "XXXXXXXXX",
      "language_code": "pt_BR",
      "data": {
          "text": "The product {{1}} arrived!"
      }
   },
   "contacts":[
      {
        "id":"5511999999999",
        "params": ["123"]
      },
      {
        "id":"55163333333333",
        "params": ["abc"]
      }
   ]
}

Sending Image

POST https://api.cosmobots.io/messages/v1/broadcast

{
   "message": {
      "type": "media",
      "template_id": "XXXXXXXXX",
      "language_code": "pt_BR",
      "data": {
          "type": "image",
          "url": "URL_Image",
          "text": "The product arrived!"
      }
   },
   "contacts":[
      {
        "id":"551199999999"
      }
   ]
}

POST https://api.cosmobots.io/messages/v1/broadcast

{
   "message": {
      "type": "media",
      "template_id": "XXXXXXXXX",
      "language_code": "pt_BR",
      "data": {
          "type": "image",
          "text": "The product arrived!"
      }
   },
   "contacts":[
      {
        "id":"551199999999"
      }
   ]
}

Sending ButtonsType: Text

POST https://api.cosmobots.io/messages/v1/broadcast

{
   "message": {
      "type": "text",
      "template_id": "XXXXXXXXX",
      "language_code": "pt_BR",
      "data": {
          "text": "The product {{1}} arrived! | [Button 1] | [Button 2]"
      }
   },
   "contacts":[
      {
        "id":"551199999999",
        "params": ["123"]
      }
   ]
}

Sending Buttons Type: URL

POST https://api.cosmobots.io/messages/v1/broadcast

{
   "message": {
      "type": "interactive",
      "template_id": "XXXXXXXXX",
      "language_code": "pt_BR",
      "data": {
          "type": "URL",
          "text": "The product {{1}} arrived! | [Button 1,https:url.com.br]"
      }
   },
   "contacts":[
      {
        "id":"55119999999",
        "params": ["123"]
      },
      {
        "id":"55113333333",
        "params": ["ABC"]
      }
   ]
}