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"]
      }
   ]
}

Last updated