WhatsApp Flow

uContact has integrations with major messaging service providers. However, you can create your own integration with a provider not included in uContact using the Flow Designer. Let us show you how!

Custom Providers

These providers can be integrated fully or partially depending on the capabilities of the external service or usage needs.

For example:

• For a dialer, it may be sufficient to implement only message sending.
• For a customer service, it's necessary to implement sending, receiving, and status updates (sent, received, read, etc.).

Initial Connector Configuration

Before creating the flows, you need to configure the connector in uContact. Below we show you the step-by-step process.

1. First, go to the Administration Menu and access the Connectors section. Then, click the New button located in the upper right corner.

2. In this modal, you need to enter a unique name for the connector, select the WhatsApp channel and the Flow provider.

3. Then, two new sections will appear. You need to access the Configuration section to create the flows and integrate with the provider.

In this step, you'll need to create two flows:

• One for sending messages
• Another for ending the interaction

Learn how to develop these flows by clicking here.

Numbers

Phone List: Here you need to add the numbers the connector will use to send and receive messages. You can add them manually or in bulk using a list of numbers.

How to add a number?

To add a number, simply enter it in the Phone Number field and then click the + button.

Once added, you can view it in the list.

For each number you will have the option to:

• Copy: this option copies the number to the clipboard.
• Delete: this option allows you to delete the number from the connector. To delete it, you need to save the connector.

How to upload a number list?

To upload a number list, you need to click the button shown below.

Then, the data import wizard will open.

• Step 0: the required fields are displayed.

• Step 1: you have to drag the list or select it from your computer. It must be in XLSX, ODS, CSV, or TXT format.

• Step 2: you will see the first 3 records of the list in the left column, and in the right column you must associate it to the Phones option. Additionally, if you included a header in the list, for example, Numbers, you need to select the Contains headers option.

• Step 3: finally, in this step you simply need to click Finish.

Flow Development

To create these flows, you need to click on the button with the flow name within the configuration and the uContact Flow Designer will open so you can create the corresponding flow.

You can find more information about the Flow Designer by clicking here.

Available Variables

Within the flows, there are several available variables you can use. Below we show you what they are and what you can use them for.

Agent

Stores the agent's name in case there is an interaction.

• Type: String

Message

Stores the message sent by the agent.

• Type: String

To

Stores the recipient's number.

• Type: String

Attachments

An array of objects, where each one stores an attachment.

• Type: Array

Here's an example!

[
  {
    "extension":"png",
    "path":"20210226/8b5eb91a-2799-4c30-a712-9cfbbd333f49.1584030188436.png",
    "url":"https://example.ucontactcloud.com/attachments/20210226/8b5eb91a-2799-4c30-a712-9cfbbd333f49.1584030188436.png",
    "type":"image/png"
  }
]

What does each property mean?

• extension: indicates the file extension.
• path: indicates the file name.
• url: indicates the URL where the file is located.
• type: indicates the MIME type of the file.

Campaign

Stores the name of the interaction's campaign.

• Type: String

GUID

Stores the unique identifier of the interaction.

• Type: String

SMS_GUID

Stores the unique identifier of the message.

• Type: String

REFERENCE_ID

Stores the ID of the message being replied to. This function is only compatible with WhatsApp.

• Type: String

Message Sending

To implement message sending, you need to create a flow using the Flow Designer with the following activities:

1. Provider

This activity marks the start of the provider flow and is already included by default in the flow, so you don't need to add it.

2. ExecWebService

Using the available variables, you must execute the call to the external provider service with this activity. This is where the HTTP request to the messaging provider's API is made.

3. MessageResult

When you have the execution result, you need to use this activity to inform the system of:

• The result of the sending.
• The unique message ID with which the service responded.

This ID will be useful later to update the message status (sent, received, read, etc.).

To save changes, you need to click Production and then close the Designer.

Interaction Close Notification

It's possible and optional to execute an event when a uContact interaction ends, if it's associated with a custom provider.

What is it used for?

Normally, this flow will simply be an execution to an external service to notify the closing of the conversation. For example:

• Notify the provider's system that the conversation has ended
• Update the session status in an external CRM
• Execute any necessary cleanup or closing logic

After executing the call to the external service, nothing else needs to be added to the flow.

Required Webhooks

In addition to the two flows, it's possible to configure two Webhooks to receive messages and to update message statuses (only for WhatsApp).

Message Reception

To receive messages in uContact, you need to create an incoming webhook flow. This webhook will allow the external provider to notify uContact when a new message arrives.

You can find more information about creating Webhooks in the Functions guide.

ReceiveNewMessage

In the webhook flow, you must use the ReceiveNewMessage activity to inform the system of the reception of a new message.

DID Parameter

An important aspect is that in this activity you indicate which number the message was sent to with the "did" field. For the message to be directed to a specific campaign, the campaign must have the same "did" number configured.

For example:

• If the webhook receives a message sent to the number +1234567890
• And there is a campaign with the "did" configured as +1234567890
• Then the message will be automatically routed to that campaign

Status Updates

The status update of sent messages allows notifying uContact when a message's status changes (sent, delivered, read, failed, etc.).

MessageStatus

To update a message's status, use the MessageStatus activity in the webhook flow.

Important Requirement

Status updating is only possible if the outgoing message ID returned by the provider at the time of sending was provided (described in the Message Sending section with the MessageResult activity).

The typical flow is:

1. uContact sends a message and receives the ID from the provider
2. The provider notifies status changes via webhook
3. uContact updates the message status using the received ID

Important Considerations

• It's possible to use JavaScript within the Flow Designer to analyze the body content and perform complex actions.
• It's recommended, if possible, to design a simple API on the provider side to reduce flow complexity and simplify maintenance.
• The "did" field must match exactly between the webhook and campaign configuration for correct message routing.
• Message IDs provided by the provider must be unique and consistent to allow status tracking.