# V1 - Send Message

This document is intended to be used for developers using CosmoBots API to send and receive messages, to single contacts per request, on channels connected to CosmoBots.

To send messages to registered channels we are considering you already have connected the channel to your Bot on CosmoBots.

## Endpoint

```
POST https://api.cosmobots.io/messages/v1/send
```

## Authentication

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:

* Login into the platform
* Choose the Bot
* On the left sidebar menu, choose Integrations, then API
* Choose the Send Message API
* Click on Enable API
* Now you can copy both token and channelId to use on the requests

| Header          | Type   | Description                                                       |
| --------------- | ------ | ----------------------------------------------------------------- |
| **token**       | String | **Required.** Token exclusive to the Bot, to be used on this API. |
| **channel\_id** | String | **Required.** ID of the Channel that will receive the messages    |

## Sending Message

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

| Field           | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **destination** | String | <p><strong>Required.</strong> </p><p>Destination that the message will go.</p><ul><li>bot</li><li>contact</li><li>desk</li></ul><p><strong>If bot:</strong> it will send to the bot and reply through the webhook if sync or on the same request through a response if async).<br></p><p><strong>If contact:</strong> it will send to the contact. And any reply back from the contact will be handled through the webhook.<br></p> |

###

### Contact *`Object`*

| Field             | Type               | Description                                                                                                                                                                                  |
| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**            | String             | **Required.** ID of the Contact on CosmoBots. If it is a new contact then just inform "new\_contact"                                                                                         |
| **external\_id**  | String             | ID of the Contact on any external Database                                                                                                                                                   |
| **first\_name**   | String             | First Name of the Contact                                                                                                                                                                    |
| **last\_name**    | String             | Last Name of the Contact                                                                                                                                                                     |
| **mobile\_phone** | String             | Mobile Phone of the Contact. It is required when using these channels: whatsapp, rcs, apple. It needs to provide the number with complete format, including country code. Ex.: 5511999999999 |
| **custom**        | Object (Key/Value) | Custom fields about the contact profile                                                                                                                                                      |

###

### Session *Object*

| Field       | Type   | Description                                                                                               |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------- |
| **id**      | String | **Required.** ID of the Session                                                                           |
| **control** | String | <p></p><p>It shows who controls the conversation. The options are:</p><ul><li>bot</li><li>human</li></ul> |
| **desk**    | Object | Provide the desk platform that is being used by the human agent                                           |
| **context** | Object | Information about the context of the conversation                                                         |

###

### Desk *`Object`*

| Field        | Type              | Description                                                                                                                       |
| ------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **provider** | String            | **Required.** Provider of the Desk platform                                                                                       |
| **agent**    | Object < String > | <p></p><p>Information about the person handling the conversation</p><ul><li>id</li><li>name</li><li>email</li><li>group</li></ul> |

###

### Message *`Array [Object ]`*

| Field            | Type   | Description                                                                                                                     |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **data**         | Object | **Required.** Data related to the message                                                                                       |
| **type**         | String | <p></p><p>Types of Message. Options are: </p><ul><li>text</li><li>buttons</li><li>cards</li><li>media</li><li>payload</li></ul> |
| **template\_id** | String | ID (or Name) of Template approved by Facebook to be sent.                                                                       |

###

### 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></p><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></p><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                                                                                                            |
| **name**       | String | Name of the Media (Caption)                                                                                                               |
| **mime\_type** | String | The media type standard                                                                                                                   |

### Response *Sync*

| Field            | Type            | Description                                                             |
| ---------------- | --------------- | ----------------------------------------------------------------------- |
| **status**       | String          | <p></p><p>Status of the Message</p><ul><li>sent</li><li>error</li></ul> |
| **contact\_id**  | String          | ID of the Contact                                                       |
| **session\_id**  | String          | ID of the Session of the ongoing conversation                           |
| **message\_ids** | Array \[String] | Array with the ID's of the messages sent                                |

###

### Response *Async*

| Field  | Type   | Description                       |
| ------ | ------ | --------------------------------- |
| **id** | String | ID confirmation of message queued |

##

## Examples of Request

### Sending Text `Destination: Bot`

```
POST https://api.cosmobots.io/messages/v1/send

{
   "destination":"bot",
   "contact": {
       "id": "new_contact",
       "external_id": "123456",
       "firstName": "John",
       "phone": "5511999999999",
       "custom": {
          "email":"test@test.com"
       }
   },
   "message":[{
      "type":"text",
      "data":{
         "text":"How was my service?"
      }
   }]
}
```

### Sending Text with Buttons `Destination: Contact`

```json
POST https://api.cosmobots.io/messages/v1/send

{
   "destination":"contact",
   "contact": {
       "id": "XXXXXXXXX",
       "external_id": "123456",
       "phone": "5511999999999"
   },
   "message":[{
      "type":"buttons",
      "data":{
         "text":"How was my service?",
         "buttons":[
            {
               "title":"Good",
               "type":"text",
               "value":"good"
            },
            {
               "title":"Great",
               "type":"text",
               "value":"great"
            }
         ]
      }
   }]
}
```

### Sending Audio `Destination: Bot`

```json
POST https://api.cosmobots.io/messages/v1/send

{
   "destination":"bot",
   "channel":"whatsapp",
   "contact": {
       "id": "new_contact",
       "external_id": "123456",
       "firstName": "John",
       "phone": "5511999999999",
       "custom": {
          "email":"test@test.com"
       }
   },
   "message":[{
      "type":"media",
      "data":{
         "type":"audio",
         "name":"sample_audio",
         "url":"https://xy.com/x.wav",
         "mime_type":"audio/wav"
      }
   }]
}
```

### Sending Image `Destination: Contact`

```
POST https://api.cosmobots.io/messages/v1/send

{
   "destination":"contact",
   "channel":"whatsapp",
   "contact": {
       "id": "XXXXXXXXX",
       "external_id": "123456",
       "phone": "5511999999999"
   },
   "message":[{
      "type":"media",
      "data":{
         "type":"image",
         "name":"sample_image",
         "url":"https://xy.com/x.jpg",
         "mime_type":"image/jpg"
      }
   }]
}
```

## Receiving Message

To receive messages coming from CosmoBots, you have to register your endpoint on our webhook. You may find the webhook setup on the Channels section of the platform. Follow these steps:

* Login into the CosmoBots platform
* Choose the Bot
* On the left sidebar menu, choose Channel, then the specific channel you are using
* On the Webhook Url field, include the endpoint that will receive the requests

The Body fields are the same as the fields from the Body of the Sending Message request above.<br>