✉️Message API

This is a guide on how you can use Orimon message API to embed our responses into you own applications!

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

Endpoint

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

Request Headers

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 for a step-by-step guide on how to generate this key.

Content-Type : "application/json"

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

Example :

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

Request Body

type : "message"

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

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 for a guide on how to get "tenantId".
• platformName : has the fixed value of "web", signifying that you are using the web API to get a response.

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 :

{
    "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

// 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:

{
    "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.

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.