"app_type": ["communication"]

Creating a communication app lets you integrate 3rd party messaging channels (e.g. Messanger, WhatsApp, etc.) into vcita's conversation page.

This can be a good solution for businesses that have a business page on social networks and want to be able to send and receive messages through these networks within vcita and manage the entire interaction with their clients from one place.

In order to support such use cases, vcita created the infrastructure that allows sending messages to vcita's conversion page and getting notified when new messages are sent from this page.

🚧

Handling communication with 3rd party messaging channels

Pushing messages to the 3rd party communication channel and listening to new events from these channels is the developer's/business responsibility.

Injecting messages to vcita from external messaging channels is done using the "vcita Communication Service" (VCS).
VCS exposes the necessary APIs that allow external messaging apps to push messages into vcita and also get notified when a message is sent out from vcita to the messaging app.

📘

Middleware Service

A service that can (a) listen to new messages sent from 3rd party messaging apps, and (b) push messages back to these apps.

The middleware service can be an existing service provider (like Smootch) or an in-house solution.
Either way, it should be able to perform the tasks listed above.

📘

Main App

The main application is responsible for syncing messages between vcita and the 3rd party messaging apps.
This app will interact with both the middleware service and VCS.

📘

vcita Communication Service - VCS

A vcita's service that enables external services to get notified on new messages sent from vcita and also to inject new messages to vcita's client conversation page.

Once new channels are created, staff members will be able to choose the channel through which they want to send messages to the client, and in the same way, the conversation page thread will reflect the channel that a message was sent from.

• Creating an app of type "communication"
• Make sure you can generate an OAuth access tokens for the businesses that need to be connected to the channel
• Building the Main App that will be responsible for:
  (a) implementing the communication app interface
  (b) communicating with VCS APIs

For the purpose of this guide, let's assume we are building a channel for WhatsApp messages.

Step 1. Creating the communication app

curl --location --request POST 'https://api.vcita.biz/platform/v1/apps' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "WhatsApp Channel",
    "app_type": ["communication"],
    "trusted": true,
    "url_params": ["business_uid", "staff_role", "staff_uid"],
    "redirect_uri": "OAUTH-REDIRECT-URI",
    "api_uri":"{REGISTERED_APP_URI}"
}'

📘

app_uri

The app_uri is the dedicated route on your main app that vcita will send updates and webhooks to.
Thus, when building the main app on your end, it'll have to include a dedicated route for VCS events.

Later on, we will go through the different child routes that it has to implement (See below appendix Communication App Interface).

In this guide we will refer to the app_uri as the "app-registered-uri".

🚧

Storing app info

After creating your app in vcita, make sure to store the "client_id", "client_secret", "app_code_name", "and app_id" values returned in the Create App API response.
These will be needed for later authentication tasks.

Step 2. Generating OAuth tokens

Ensure you can generate OAuth tokens for the businesses you want to connect to the messaging channel and store these tokens in a database for future use.
Make sure you're able to generate, store, and retrieve these tokens dynamically.
These tokens will be used for creating and managing sessions on behalf of these businesses.
For further info regarding OAuth tokens, please refer to this article.

Step 3. Building the Main App

On your end, you need to build an app that will know to (a) listen to webhook events from vcita, and (b) update vcita upon new messages or status updates that occur on the 3rd party communication channel.
This app is eventually a middleware that will handle the communication between the 3rd party messaging channel and vcita's communication service.

Listening to webhook events from vcita

The main app needs to implement the necessary routes listed in this guide under the "Communication-App Interface" appendix.
As explained above, vcita will send webhooks to these routes in order to update your app when new messages/sessions/channels are created, or have their status updated.

Updating vcita

In order to update vcita when a new message is created on the 3rd party messaging app, or when a session changed its status, etc. vcita developed a set of APIs that allow you to communicate with our communication service and perform all necessary actions.

Communication API reference

Please refer to this swagger file for detailed API specs.
We will also go through these API endpoints in this guide.

VCS is built upon 4 main building blocks:

• Communication app
• Channel
• Sessions
• Messages

The communication app is the main entity that manages the interaction between the external messaging service and VCS.
When creating a new communication app and assigning it to a business, you'll instantly see it reflected in the conversation page as an additional messaging channel.

A channel represents the implementation of a communication app at the business level.
When assigning a communication app to a business, the app needs to create a new channel for the business and wait for the confirmation webhook before it can open messaging sessions with clients.

When creating a channel you'll need to specify the:
(a) "business_uid": uid of the business the channel is created for.
(b) "type": messaging channel type. Can be either "transactional" or "promotional".
You'll usually use the "transactional" option, which relates to messages sent to, and from, the clients' conversation page.

The response from the POST request will indicate the newly created channel's status is "pending", and also includes the channel uid.
Once the channel is validated on vcita, we will trigger a webhook indicating the status is "active".

Channel creation
Sending a POST /business/communication/channels
Receiving PUT to /channels/:channel_uid

📘

Communication app identification

You'll notice that the create channel request does not include the communication app id or name in it.
Our way of identifying the communication app that the channel is created for is by the API token used in the request.
Therefore, you have to generate a dedicated token for the communication app using its client id and secrete, as explained here.

A session represents a conversation thread with a client via a given channel.
Thus if a staff member wants to send a message to a client via WhatsApp, the communication app created for WhatsApp needs to create a channel with that business, and then create a session using that channel for the client.

When creating a session you'll need to specify the:
(a) "business_uid"
(b) "channel_uid": the channel that the session created for (keep in mind that you can connect multiple channels to the one business).
(c) "contact_uid": uid of the contact (client or matter) that the session is created for.
(d) "external_uid": client's identifier on the main app.

The response from the POST request will indicate the newly created session's status is "pending", and also includes the session uid.
Once the session is validated on vcita, we will trigger a webhook indicating the session status is "active".

🚧

Sessions

Sessions are singular per client and channel.
Thus when switching between channels there is no need to create new sessions each time, and a channel can use its existing session by activating it.
As a rule of thumb - there should be only one session per client for a given channel.

The message is the actual text message that is sent during an active session.

When creating a message you'll need to specify:
(a) "message": the actual message (text) sent by the client
(b) "channel_uid": the channel through which the message was sent from.
(c) "message_uid": uid of the message. Will be used for later webhook events indicating whether the message was sent successfully or not.
(d) "external_uid": client's identifier on the main app.

The response from the POST request will indicate the newly created message status is "pending", and also includes the message uid.
Once the message is validated on vcita, we will trigger a webhook indicating the status is "active".

Child routes that the main app needs to implement under the redirect URI route

Channels

Method: PUT
Route: /channels/{channel_uid}
Response codes:
-204 - Message received successfully
-4xx/5xx - Error receiving message
Payload:

{
  "status”: ChannelStatus
}

Sessions

Receive session update

Method: PUT
Route: /sessions/{session_uid}
Response codes:
-204 - Message received successfully
-4xx/5xx - Error receiving message
Payload:

{
  “status”: SessionStatus
}

Messages

Receive new message

Method: POST
Route: /messages
Response codes:
-204 - Message received successfully
-4xx/5xx - Error receiving message
Payload:

{
  "external_uid": string, // App's contact identifier
  "message": string,
  "message_uid": string, //  uuid of message (unique per channel). App will send message updates based on this message identifier
  "channel_uid": string,
  “status”: MessageStatus // Current status of message
}

Receive message update

Method: PUT
Route: /messages/{message_uid}
Response codes:
-204 - Message received successfully
-4xx/5xx - Error receiving message
Payload:

{
  "status”: string,
  "channel_uid": MessageStatus
}

• pending - Channel has been registered but not yet active
  • active - Channel is active and messages can be send to/from
  • inactive - Channel is temporary inactive
  • blocked - Channel is blocked for unexpected reason
  • deleted - Channel is explicitly deleted by user/business

• transactional - Channel dedicated for regular messaging
• promotional - Channel dedicated for promotional offers

• pending - Session has been created and waiting for confirmation
  • active - Session of a channel is open and ready to send and receive messages
  • inactive - Session of a channel is established but cant send and receive messages.

• pending - New message was received by service but not yet displayed to user/business
• received - Message was successfully displayed to user/business
• read - Message was read by user/business
• error - Message delivery encountered some error that needs to be handled

Listening to typing events within vcita, and notifying vcita when a user is typing in the 3rd party messaging app, can be easily achieved by implementing the following:

Create the following endpoint on your end:
{app_registered_uri}/{session_uid}/typing
Example:
https://app-registered-uri.com/c6f6217f-bf44-4ed0-84d1-0ef82149bf54/typing

The payload vcita sends upon typing state change is:

{
  typing: boolean
}

Based on the session_uid URL param you should be able to determine the channel and client id that their state needs to be updated on the 3rd party app.

curl --location --request POST 'https://api.vcita.biz/business/communication/v1/sessions/typing' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "session_uid": string,
    "typing": boolean
}'