App development for a Marketplace using External Lines

App Registration

To register your app in our system, prepare and provide the following information ⬇️

☝🏻 Tip:

• code is the unique code of your integration;
• callback_url is the URL to which app installation and uninstallation requests will be sent. For these actions, /portals/install and /portals/uninstall are appended to the callback_url, respectively;
• price is set to true if your integration is paid and to false if it is free;
• sns_subscription_url is the URL to which events about new messages in External Channels will be sent.

After providing this information, you will receive a client_id and secret_id for further development.

Backend Development

We have prepared a Laravel PHP template with basic settings. Review the link

App Installation

When a user installs the app, you will receive the following request:

You need to save:

• token – valid for 1 day
• refresh_token – valid for 30 days
• expiry_date – to check the token's validity. The value must be specified in seconds.

It is recommended to create a cron job to update portal tokens.

Access Token Renewal

In the previous step, we obtained a token. This token has a lifetime of 1 day, after which requests using it will stop working. To renew the token, we recommend using the following request:

App deletion

When the app is uninstalled, you will receive:

Working with External Lines (EL)

Creating external line

To send messages to external lines (EL), you first need to create them. Typically, one connection has one EL. For example, in the Instagram app, the user can add multiple accounts (connections), and we create a separate EL for each of them.

☝🏻 Tip:

• name is the unique name;
• icon is the URL of the icon. This image will be displayed in the bottom-right corner of the chat icon on the External Lines tab;
• phoneNumber is the phone number, if available. If your integration does not use phone numbers, you can use the same value as in the name field;
• externalId is the unique identifier of the External Line.

☝🏻 Save the identifier of the created EL, as you will need it later.

​

Creating a Chat

Next, you need to create a chat. If, for example, webhooks will be receiving events about messages, then having the identifier of the user sending these messages, you can create a chat. Then, in subsequent similar events, you will know which chat to send the processed messages from your service to the EL.

☝🏻 Tip:

• externalLines is the ID of the External Line created earlier;
• meta is used to link the chat to CRM;
• meta.type supports the following values: phone, widgetUser, username, facebook, instagram, telegram, twitter, viber, or whatsapp;
• meta.value can contain a phone number or an ID.

☝🏻Save the identifier of the created chat.

These are the basic required fields.

Sending Messages

If your message will contain attachments, you need to upload them first.

1. Uploading files (if needed):

2. Sending a message:

☝🏻 Tip:

• type — see the documentation for more information about the available message types ➡️ HERE;
• externalAuthorId is the ID of the message sender;
• parentMessage is the ID of the parent message;
• attachedFiles is an array of files uploaded in the previous step.

3. Receiving a message event:

When you registered the app, you provided the sns_subscription_url field. We will send a webhook about the message in the EL to this URL. You need to check the event that comes in and extract only the payload. For example, you can use the nipwaayoni/laravel-aws-sns package for PHP and add the following code to the controller:

Here is an example of a received message event with an image:

After that, we recommend checking that it is a message, and that it is from the EL:

Next, you can find the corresponding chat in your system by the chatId identifier.

If you have additional questions or you need to contact the support, send a request to this email [email protected]