Messaging Setup Guide

This guide walks through configuring SMS and WhatsApp messaging end-to-end. After completing these steps, agents in Thirdlane Connect will be able to send and receive messages through the configured channels.

Both SMS and WhatsApp share the same routing and channel architecture. The main difference is in provider setup: SMS uses a messaging gateway, while WhatsApp uses a Meta Business Account.

---

SMS Setup

1. Configure a Messaging Gateway

A messaging gateway connects your system to an SMS provider (Telnyx, Twilio, or Bandwidth).

Where: Configuration > Telephony Settings > Messaging Gateways

1. Click Add and select your SMS provider
2. Enter the credentials provided by your SMS provider (API key, account SID, auth token, etc.)
3. Note the Domain field - this is the hostname your provider will use to deliver inbound messages
4. Save the gateway

After saving, the system generates a webhook URL. Configure this URL in your SMS provider’s portal so they can deliver inbound messages and status updates.

2. Assign DIDs to the Gateway

Each DID that will send SMS needs an outbound SMS route pointing to the gateway.

Where: Configuration > Telephony Settings > Outbound SMS Routes

1. Select the DID you want to SMS-enable
2. Choose the messaging gateway created in step 1
3. Save

3. Create an Inbound Messaging Route

An inbound messaging route tells the system where to deliver messages that arrive on a DID.

Where: Tenant > Routing > Inbound Messaging Routes

1. Click Add
2. Select the DID
3. Choose a destination: a specific user (direct delivery) or a queue (distributed to agents)
4. If you choose a queue destination, check Create outbound SMS channel - this automatically creates a messaging channel and assigns it to the queue, saving you the next step

If you used the auto-create checkbox, skip to step 5. Otherwise, continue to step 4.

4. Create a Messaging Channel

A messaging channel is a named outbound sender identity that agents see in Connect.

Where: Tenant > Messaging > Channels

1. Click Add
2. Set Type to SMS
3. Enter a descriptive Name (e.g., “Support SMS”) - this is what agents see
4. Select the DID configured in step 2
5. Use the Queues shuttle to assign this channel to the queue(s) whose agents should use it
6. Optionally enable Require Templates if agents should only send pre-approved messages
7. If Require Templates is enabled, assign Message Templates in the SMS Templates section
8. Save

5. Verify the Setup

At this point:

• Inbound SMS to the DID will route to the configured user or queue in Connect
• Agents in the assigned queue(s) can send SMS replies using the channel’s DID
• If the queue has only one SMS channel, it is auto-selected for the agent

If this doesn’t work	Check
Inbound messages not arriving	Messaging gateway webhook URL configured at provider; inbound messaging route exists for the DID
Agent cannot send	Messaging channel is active; channel is assigned to the agent’s queue; DID has an outbound SMS route
Agent does not see the channel	Channel status is active; channel is assigned to the queue; agent is a member of the queue

---

WhatsApp Setup

1. Prepare Your Meta Business Account

Before configuring anything in the system, you need these from Meta:

• A Meta Business Account with access to the WhatsApp Business Platform
• A WhatsApp Business Account (WABA) created in Meta Business Manager
• A System User Access Token with whatsapp_business_messaging and whatsapp_business_management permissions
• At least one phone number registered with your WABA
• The App Secret from your Meta App settings

2. Create a WhatsApp Business Account

Where: Tenant > Messaging > WhatsApp Accounts

1. Click Add
2. Enter a Name (e.g., “Main WABA”)
3. Enter your WABA ID from Meta Business Manager
4. Enter the Access Token (system user permanent token)
5. Enter the App Secret from your Meta App
6. Set a Verify Token (any secure random string you choose - you’ll need this again in step 5)
7. Save
8. Click Test Connection to verify the credentials are working

3. Sync Phone Numbers and Templates

Still on the WhatsApp Accounts screen:

1. Select your account and click Sync Phones to pull all registered phone numbers from Meta
2. Click Sync Templates to pull all approved message templates from Meta

Verify that your phone numbers appear with the correct display number, verified name, and quality rating.

4. Map a WhatsApp Phone Number to a DID

The system routes all messaging (SMS and WhatsApp) through DIDs. A WhatsApp phone number must be linked to a DID so the system knows which WhatsApp number corresponds to which business line.

Where: Tenant > Messaging > Number Mapping

1. Find the DID you want to link
2. Select the WhatsApp phone number from the dropdown
3. Save

After mapping, the DID grid shows a WA badge on linked numbers.

5. Configure the Meta Webhook

Meta needs to know where to send incoming WhatsApp messages. In your Meta App settings:

1. Navigate to WhatsApp > Configuration > Webhook
2. Set the Callback URL to https://your-server-domain/whatsapp (use the same domain as your Thirdlane management interface)
3. Set the Verify Token to the same value you entered in step 2
4. Subscribe to the messages webhook field

6. Create an Inbound Messaging Route

Just like SMS, inbound WhatsApp messages are routed by DID.

Where: Tenant > Routing > Inbound Messaging Routes

1. Click Add
2. Select the DID you mapped in step 4
3. Choose a destination: user or queue
4. If you choose a queue destination, check Create outbound WhatsApp channel - this auto-creates the channel and assigns it to the queue

If you used the auto-create checkbox, skip to step 8. Otherwise, continue to step 7.

7. Create a Messaging Channel

Where: Tenant > Messaging > Channels

1. Click Add
2. Set Type to WhatsApp
3. Enter a descriptive Name (e.g., “Support WhatsApp”)
4. Select the DID mapped to your WhatsApp phone number
5. Use the Queues shuttle to assign this channel to queue(s)
6. In the WhatsApp Templates section, assign the templates agents should be able to use on this channel
7. Save

Note

WhatsApp channels always require templates for initiating conversations outside the 24-hour messaging window. The Require Templates option is automatically enabled and locked for WhatsApp channels.

8. (Optional) Configure Template Variable Mappings

If your templates contain variable placeholders ({{1}}, {{2}}, etc.), you can pre-map them to CRM contact fields so values are filled automatically at send time.

Where: Tenant > Messaging > WhatsApp Accounts > select account > Templates grid > click pencil icon on a template

For each variable, configure:

• Source - Contact Field, Account Field, Custom Field, Static Value, or Agent Enters
• Field - the specific field to pull the value from
• Default Value - fallback if the field is empty

9. Verify the Setup

At this point:

• Inbound WhatsApp messages to the mapped number will route to the configured user or queue in Connect
• Agents can reply within the 24-hour conversation window
• Agents can initiate conversations using approved templates
• Template variables are pre-filled from CRM data (if mappings are configured)

If this doesn’t work	Check
Inbound WhatsApp messages not arriving	Meta webhook URL and verify token configured correctly; WhatsApp phone is mapped to a DID; inbound messaging route exists for that DID
”Test Connection” fails	WABA ID, access token, and app secret are correct; token has required permissions
No phone numbers after sync	Phone numbers are registered under the correct WABA in Meta Business Manager
Agent cannot reply via WhatsApp	Messaging channel is active and assigned to the queue; DID is mapped to a WhatsApp phone; 24-hour window has not expired (use a template to re-initiate)
Template variables show as empty	Variable mappings are configured; CRM contact record has the mapped fields populated

---

Using Both SMS and WhatsApp on the Same Number

A single DID can have both an SMS gateway and a WhatsApp phone number mapped to it. In this case:

1. Create two messaging channels for the same DID - one of type SMS, one of type WhatsApp
2. Assign both channels to the same queue
3. Create one inbound messaging route for the DID - the system routes inbound messages based on protocol (SMS vs WhatsApp) automatically

Agents in Connect will see both channels available and can choose the appropriate one when initiating outbound conversations. For inbound messages, the system preserves the original protocol - an SMS conversation stays SMS, a WhatsApp conversation stays WhatsApp.