V1 - Send Message

Send and receive messages, to single contacts per request, on channels connected to CosmoBots

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	Required. Destination that the message will go. bot contact desk If bot: it will send to the bot and reply through the webhook if sync or on the same request through a response if async). If contact: it will send to the contact. And any reply back from the contact will be handled through the webhook.

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	It shows who controls the conversation. The options are: bot human
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 >	Information about the person handling the conversation id name email group

Message Array [Object ]

Field	Type	Description
data	Object	Required. Data related to the message
type	String	Types of Message. Options are: text buttons cards media payload
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	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
name	String	Name of the Media (Caption)
mime_type	String	The media type standard

Response Sync

Field	Type	Description
status	String	Status of the Message sent error
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":"[e-mail]"
       }
   },
   "message":[{
      "type":"text",
      "data":{
         "text":"How was my service?"
      }
   }]
}

Sending Text with Buttons Destination: Contact

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

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":"[e-mail]"
       }
   },
   "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.