Create Channel

Effortlessly set up an API channel inbox in Bevatel, allowing you to send and receive messages using Bevatel APIs with simple configuration steps.

How to create an API channel inbox?

Setting up an API channel consists of the following steps.

1. Create API Channel inbox
2. Send messages using Bevatel APIs
3. Receive webhooks on new messages from Bevatel

This document allows you to create and configure an API channel inbox in Bevatel installations.

Step 1: Go to Settings > Channels and click on "Add Channel".

Step 2: Select API from the list of channels.

Step 3: Provide a name for the channel and a callback URL (the events and corresponding payload are defined in 
the subsequent articles)

Step 4: Add agents to the channel

Step 5: Hooray!! The inbox setup is complete.

Now the channel setup is complete, let us try to send a message using Bevatel APIs.

When the user tries to edit the inbox configuration

In the inbox configuration's collaborators section:

• When you add an agent in the Agent field, any user designated as an agent can see and access this inbox from the Conversation module. They can manage conversations in this inbox.
• However, when you add a team in the Team field, users attempting to assign conversations to a specific team from the Conversation module will only see the teams that have been added to the related inbox. This restricts conversation assignment options to the teams associated with the particular inbox, ensuring that conversations are appropriately distributed among the specified teams.
  
  

Send messages

Learn how to send messages in an API channel within Bevatel by creating contacts, conversations, and messages with the help of API access tokens and structured payloads for efficient communication.

Send messages to the API channel

To send messages to the API channel, you need to have a basic understanding of the models and nomenclature used in Bevatel. Let us try to understand these first.

1. Channel: You can create multiple sources of conversations that are of the same channel type. For eg: You can have more than one Facebook page connected to Bevatel account. Each page is called as the channel in Bevatel.
2. Conversation: A Conversation is a collection of messages.
3. Contact: Each conversation has a real-life person associated with it, this person is called a contact.
4. Contact Inboxes: This is the session for each contact on an inbox. A contact can have multiple sessions and multiple conversations in the same inbox.

How to send a message in an API Channel?

To send a message in an API channel, you have to create a contact, then create a conversation, and then send a message.

APIs require api_access_token in the request header. You can get this token by visiting your Profile settings > Access Token

1. Create a contact

Pass the inbox ID of the API channel along with other parameters specified. This would create a session for you automatically. A sample response would look like the one below.

28. {
29.   "email": "string",
30.   "name": "string",
31.   "phone_number": "string",
32.   "thumbnail": "string",
33.   "additional_attributes": {},
34.   "contact_inboxes": [
35.     {
36.       "source_id": "string",
37.       "inbox": {
38.         "id": 0,
39.         "name": "string",
40.         "website_url": "string",
41.         "channel_type": "string",
42.         "avatar_url": "string",
43.         "widget_color": "string",
44.         "website_token": "string",
45.         "enable_auto_assignment": true,
46.         "web_widget_script": "string",
47.         "welcome_title": "string",
48.         "welcome_tagline": "string",
49.         "greeting_enabled": true,
50.         "greeting_message": "string"
51.       }
52.     }
53.   ],
54.   "id": 0,
55.   "availability_status": "string"
     }

As you can see in the payload, you will be able to see the contact_inboxes and each contact_inbox will have a source_id. Source ID can be seen as the session identifier. You will use this source_id to create a new conversation as defined below.

2. Create a conversation

Use the source_id received in the previous API call.

You will receive a conversation ID, which can be used to create a message.

3. {
4.   "id": 0
5. }

3. Create a new message
There are 2 types of messages.

1. Incoming: Messages sent by the end user is classified as an incoming message.
2. Outgoing: Messages sent by the agent is classified as an outgoing message.

If you call the API with the correct content, you will receive a payload similar to the one below

16. {
17.     "id": 0,
18.     "content": "This is a incoming message from API Channel",
19.     "inbox_id": 0,
20.     "conversation_id": 0,
21.     "message_type": 0,
22.     "content_type": null,
23.     "content_attributes": {},
24.     "created_at": 0,
25.     "private": false,
26.     "sender": {
27.         "id": 0,
28.         "name": "Pranav",
29.         "type": "contact"
30.     }
31. }.

If everything is successful, you will see the conversation on the dashboard as follows.

You will be notified when a new message is created on the URL specified while creating the API channel.

Receive messages

Effortlessly receive new messages in your API channel through a POST request to the specified Callback URL, providing detailed payload information for effective message handling.

Receive messages using callback URL

When a new message is created in the API channel, you will get a POST request to the Callback URL specified while creating the API channel. The payload would look like this. 

Event type: message_created

34. {
35.   "id": 0,
36.   "content": "This is a incoming message from API Channel",
37.   "created_at": "2020-08-30T15:43:04.000Z",
38.   "message_type": "incoming",
39.   "content_type": null,
40.   "content_attributes": {},
41.   "source_id": null,
42.   "sender": {
43.     "id": 0,
44.     "name": "contact-name",
45.     "avatar": "",
46.     "type": "contact"
47.   },
48.   "inbox": {
49.     "id": 0,
50.     "name": "API Channel"
51.   },
52.   "conversation": {
53.     "additional_attributes": null,
54.     "channel": "Channel::Api",
55.     "id": 0,
56.     "inbox_id": 0,
57.     "status": "open",
58.     "agent_last_seen_at": 0,
59.     "contact_last_seen_at": 0,
60.     "timestamp": 0
61.   },
62.   "account": {
63.     "id": 1,
64.     "name": "API testing"
65.   },
66.   "event": "message_created"
67. }

Client APIs

Leverage Bevatel's client APIs to create customized customer interfaces, including chat widgets, mobile app integrations, platform extensions, for efficient customer data and interaction management.

Create Interfaces using client APIs

Note: These APIs are still in alpha, and there might be changes in the implementation in future.

Client APIs available for the API channel will help you build customer-facing interfaces for Bevatel.

These APIs are useful for cases similar to the ones described below.

1. Use a custom chat interface instead of the Bevatel chat widget
2. Build conversational interfaces into your mobile apps
3. Add Bevatel to other platforms for which Bevatel doesn't have an official SDK

Creating customer objects

You can create and retrieve customer data objects using the inbox_identifier and customer_identifier.

Inbox Identifier

You can obtain the inbox_identifier from your API channel -> Settings -> Configuration

Customer Identifier

The customer_identifier or the source_id can be obtained when creating the customer using the create API. You will need to store this identifier on your client side to make further requests on behalf of the customer. This can be done in cookies, local storage, etc.

Available APIs

Some of the things you can do via the APIs are

• Create, View and Update Contact
• Create and List Conversations
• Create, List and Update Messages

HMAC Authentication

The Client APIs also support HMAC Authentication. The HMAC token for the Channel can be obtained via running the following on your rails console.

2. # replace api_inbox_id with your inbox id
3. Inbox.find(api_inbox_id).channel.hmac_token

Connecting to the Bevatel WebSockets

To receive real-time updates from the agent dashboard, You can connect to the Bevatel WebSockets. Bevatel WebSockets connecting can be made at the following URL

1. <your installation url>/cable

Authenticating your WebSocket connection

You will start receiving the events directed towards your customer object after subscribing using the customer pubsub_token. pubsub_token is provided during the customer-created API call.

Example

2. const connection = new WebSocket('ws://localhost:3000/cable');
3. connection.send(JSON.stringify({ command:"subscribe", identifier: "{\"channel\":\"RoomChannel\",\"pubsub_token\":\""+ customer_pubsub_token+"\"}" }));