> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sympana.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messaging Connection Setup

> Create a messaging AI connection in Sympana Connector to let your Retell or Vapi agent respond to inbound messages in GoHighLevel.

## What is a messaging connection?

A messaging connection links a **messaging AI agent** (Retell or Vapi) to your GHL location. When an inbound message arrives (SMS, WhatsApp, Instagram, etc.), a GHL workflow can route it to your messaging connection, and the AI reads the message, generates a response, and sends it back through GHL Conversations.

<Warning>Messaging connections are separate from voice connections. A voice connection handles phone calls. A messaging connection handles text-based conversations. Create one of each if your AI handles both.</Warning>

***

## Create a messaging connection

<Steps>
  <Step title="Open your provider page" icon="gauge">
    In the Sympana dashboard, open the **Retell** or **Vapi** page.
  </Step>

  <Step title="Switch to Messaging Connections" icon="message">
    Click the **Messaging** tab at the top of the page (next to Voice).
  </Step>

  <Step title="Click Add Messaging Connection" icon="plus">
    Click the button to create a new messaging connection.
  </Step>

  <Step title="Enter a connection name" icon="text">
    Give it a clear name like "SMS Support Agent" or "WhatsApp Sales Bot."
  </Step>

  <Step title="Select your messaging AI agent" icon="robot">
    Choose the Retell or Vapi agent that will handle messages. This should be an agent configured for text conversations, not voice.
  </Step>

  <Step title="Select a calendar (optional)" icon="calendar">
    Only needed if the messaging agent uses appointment functions (Book Appointment, Get Slots, etc.). Skip this if the agent only handles general conversations.
  </Step>

  <Step title="Configure Contact Access" icon="shield">
    Set up who the AI is allowed to message. See [Contact Access](#contact-access) below.
  </Step>

  <Step title="Select functions" icon="wrench">
    Choose which functions the messaging agent can use — same 11 functions as voice connections (Book Appointment, Get Contact, Update Contact Data, etc.).
  </Step>

  <Step title="Configure dynamic variables" icon="code">
    Add variables the agent needs in its prompt — contact name, email, custom fields, etc.
  </Step>

  <Step title="Configure Human Handoff" icon="user">
    Set up keywords and rules for when the AI should stop and hand off to a human. See [Human Handoff](#human-handoff) below.
  </Step>

  <Step title="Save the connection" icon="floppy-disk">
    Click **Save** or **Create Connection**. The connection is now available for use in GHL workflows.
  </Step>
</Steps>

***

## Contact Access

Contact Access controls **who** the messaging AI is allowed to talk to. This prevents your AI from responding to contacts it shouldn't.

| Setting              | What it does                                                                                          |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| **Allowed Tags**     | If set, only contacts with at least one of these tags receive AI replies. Everyone else is skipped.   |
| **Blocked Tags**     | Contacts with any of these tags are skipped — AI will not respond.                                    |
| **Handoff Tags**     | Contacts with these tags are treated as "handed off to a human" — AI stops replying.                  |
| **Opt-out Keywords** | Words like `stop`, `unsubscribe`, `wrong number`. If a contact sends one of these, AI stops replying. |

### Recommended setup for outbound messaging

If you are sending outbound messages to contacts and want AI to handle replies:

1. Add a tag like `ai_msg_enabled` to the contacts you want AI to respond to
2. In the **Message Received** workflow, only call **Send AI Message** if the contact has the `ai_msg_enabled` tag
3. If a contact opts out, apply `ai_msg_blocked` and remove `ai_msg_enabled`
4. If a contact asks for a human, apply `ai_msg_handoff` to stop AI replies

<Tip>Contact Access is your safety net. It ensures the AI only talks to people you've explicitly approved, preventing unwanted automated responses.</Tip>

***

## Human Handoff

Human handoff pauses AI responses when a contact asks for a real person or when a human team member manually replies.

### How it works

<Steps>
  <Step title="Contact triggers handoff" icon="hand">
    The contact sends something like "I want to talk to a person" or "Can I speak to someone?"
  </Step>

  <Step title="Sympana detects the keyword" icon="magnifying-glass">
    Sympana checks the message against your configured handoff keywords.
  </Step>

  <Step title="Conversation is paused" icon="pause">
    The conversation is marked as handed off. The AI stops replying to this contact.
  </Step>

  <Step title="Handoff Requested trigger fires" icon="bolt">
    Sympana fires the **Handoff Requested** trigger into GHL so your workflow can take action.
  </Step>

  <Step title="Human takes over" icon="user">
    A team member replies manually inside GHL Conversations.
  </Step>
</Steps>

### Recommended handoff workflow

Build this GHL workflow to handle handoffs:

```
Trigger: Handoff Requested (Sympana)
  → Action: Add Tag "ai_msg_handoff"
  → Action: Assign contact to team member
  → Action: Send internal notification (SMS/email to your team)
  → Optional: Create Task "Follow up with {{contact_first_name}}"
```

***

## Messaging workflow

After creating a messaging connection, build a GHL workflow to use it:

<Steps>
  <Step title="Create a new workflow" icon="plus">
    In GHL, go to **Automation → Workflows** and create a new workflow.
  </Step>

  <Step title="Add the Message Received trigger" icon="bolt">
    Search for **Message Received** under Sympana Connector.
  </Step>

  <Step title="Add channel filters (optional)" icon="filter">
    Filter by channel if you only want to handle specific message types: SMS, WhatsApp, Instagram, Facebook, Webchat, TikTok, or Email.

    <Info>If no channel filter is applied, the workflow responds to ALL inbound message channels. Channel filtering belongs in the GHL trigger, not in the messaging connection itself.</Info>
  </Step>

  <Step title="Add contact tag filters (optional)" icon="tag">
    Add an If/Else condition to check for the `ai_msg_enabled` tag before sending to AI.
  </Step>

  <Step title="Add the Send AI Message action" icon="robot">
    Search for **Send AI Message** under Sympana Connector. Select your messaging connection.
  </Step>

  <Step title="Publish and test" icon="rocket">
    Publish the workflow and send a test message to verify the AI responds.
  </Step>
</Steps>

### Complete messaging workflow example

```
Trigger: Message Received (Sympana)
  → Filter: Channel = SMS
  → If/Else: Contact has tag "ai_msg_enabled"
    → Yes: Action: Send AI Message (Sympana — SMS Support Agent)
    → No: Do nothing (or notify team)
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="All Actions & Triggers" icon="bolt" href="/when-to-use-each-trigger-and-action">
    See every Sympana action and trigger available in GHL.
  </Card>

  <Card title="Configure Functions" icon="wrench" href="/functions-overview">
    Set up the functions your messaging agent can use.
  </Card>
</CardGroup>