# Message API

The Orimon Message API allows you to interact with your chat-bots using a `POST` request. 

### Endpoint

```url
 POST https://channel-connector.orimon.ai/orimon/v1/conversation/api/message
```

### Request Headers

```json
authorization : "apiKey <your_apiKey_here>"
```

* This header will include a secret API key from your Orimon Dashboard to verify its you making the request. Click [*here*](https://orimon.gitbook.io/docs/getting-started-with-apis#how-to-generate-your-developer-api-key) for a step-by-step guide on how to generate this key.

```json
Content-Type : "application/json"
```

* This header describes the format in which the request will be made.

*Example :*

```javascript
headers: { 
    'authorization': 'apiKey <your_apiKey_here>', 
    'Content-Type': 'application/json'
  },
```

### Request Body

```json
type : "message"
```

* Indicates that you are making a call to our "Message" API

```json
info : { //JSON object containing the following values
    psid : <platform_session_id>,
    sender : "user",
    tenantId : <your_tenant_id>,
    platformName : "web"
}
```

* **`psid` :** is short for platform\_session\_id which is a unique identifier, and ideally should be unique per user (user here is the end user who’ll converse with the API). Its value should be `'some_random_value' + '_' + tenantId`.
* **`sender`** : has the fixed value `"user"` as the message is being sent from user, for a response from the chat-bot.
* **`tenantId`** : This is the unique id of the chat-bot that you want a response from. Click [here](https://orimon.gitbook.io/docs/getting-started-with-apis#how-to-get-tenantid-for-your-chatbot) for a guide on how to get "**tenantId**".
* &#x20;**`platformName`** : has the fixed value of `"web"`, signifying that you are using the web API to get a response.

```json
message : { // JSON object with the following values
    id : <id_of_user_message_being_sent>
    type : "text"
    payload : { text : "some_user_text" } //JSON object with one value
}
```

* **`id`** : some unique identifier for every input that comes from user.
* **`type`** : this signifies the type of input that your bot is receiving from the user. Currently fixed to `"text"`.
* **`payload`** : The actual input that the bot will receive. The `text` key inside this object will include the user message. This will be a string value.

*Example :*&#x20;

```json
{
    "type": "message",
    "info": {
        "psid": <some_random_value + '_' + tenantId>,
        "sender": "user",
        "tenantId": <id_of_your_bot>,
        "platformName": "web"
    },
    
    "message": {
        "id": <some_unique_value>,
        "type": "text",
        "payload" : {
            "text": "some_string_value"
        }
    }
}
```

### Example Request&#x20;

```javascript
// in JS
const axios = require('axios');
let data = JSON.stringify({
  "type": "message",
  "info": {
      "psid": <some_random_value + '_' + tenantId>,
      "sender": "user",
      "tenantId": <id_of_your_bot>,
      "platformName": "web"
    },
  "message": {
      "id": <some_unique_value>,
      "type": "text",
      "payload" : {
          "text": "What is Orimon?"
    }
  }
});

let config = {
  method: 'post',
  url: 'api_endpoint_mentioned_on_top_of_this_page',
  headers: { 
    'authorization': 'apiKey <you_apiKey_here>', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});
```

### Example Response

The API response will be a JSON object with the following structure:

```json
{
    "status": "success",
    "data": {
        "type": "message",
        "timestamp": "2023-06-29T13:04:57.041Z",
        "psid": <some_random_value + '_' + tenantId>,
        "sessionId": <generated_session_id_of_current_conversation>,
        "messages": [
            {
                "chatLogId": <generated_chatlog_id_of_current_conversation>,
                "sessionId": <generated_session_id_of_current_conversation>,
                "psid": <some_random_value + '_' + tenantId>,
                "tenantId": <your_tenant_ID>,
                "id": <some_unique_value>,
                "type": "text",
                "payload": {
                    "text": "Orimon.ai is a powerful tool for businesses looking to improve online sales and conversions. It is a solution that helps businesses enhance customer education and product discovery",
                    "buttons": []
                },
                "timestamp": "2023-06-29T13:04:57.041Z",
                "customMessage": true
            }
        ],
        "statuses": []
    },
    "message": "success"
}
```

### Response Object

* **`chatLogId`** : This is a system generated id for the specific query from user and the response from your bot and can be used to identify the same.
* **`sessionId`** : This is a system generated id for the entire session that take place between your  user and your bot and can be used to identify the same.
* **`payload`** : This is the actual response and contains 2 values `"text"` and an array `"buttons"` . The `"text"` contains a string value which is the raw text response of your chat-bot and the `"buttons"` key contains an array of button options, if any buttons were configured at the specific input that the user has provided. &#x20;

### Error Handling

If there are any errors during the API request, appropriate HTTP status codes will be returned along with error messages in the response body. You can handle these errors accordingly in your application.

That's it! You should now be able to message a chat-bot using the Orimon Message API.&#x20;