# V1 - Broadcast Messages

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           | <p><strong>Required.</strong> Types of Message. Options are: </p><ul><li>Text</li><li>Buttons</li><li>Cards</li><li>Media</li></ul> |
| **template\_id**   | String           | ID of the Template being used to send the message                                                                                   |
| **language\_code** | String           | <p>Code for the language of the message.</p><p>Ex.: "pt\_BR"</p>                                                                    |
| **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 | <p><strong>Required.</strong> Type of Button, having the value related to the field payload. Options are: </p><ul><li>Text</li><li>Url</li><li>Payload</li></ul> |
| **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 | <p><strong>Required.</strong> Type of media. Options are: </p><ul><li>Image</li><li>Audio</li><li>Video</li><li>Document</li></ul> |
| **url**     | String | **Required.** Url of the Media                                                                                                     |
| **caption** | String | Caption of the Media                                                                                                               |

### Contacts *`Array [Object]`*

| Field       | Type             | Description                                                                                                                                          |
| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**      | String           | <p><strong>Required.</strong> ID of the Contact.</p><p>When the channel is WhatsApp, the id is equivalent to the phone number (complete format).</p> |
| **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 | <p>Status of the Message</p><ul><li>Sent</li><li>Error</li></ul> |
| **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 Buttons`Type: 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"]
      }
   ]
}
```