---
name: trebleai
description: Use when building WhatsApp conversation flows, creating AI agents for customer interactions, integrating with CRMs like HubSpot or Salesforce, deploying automated messaging campaigns, or configuring webhooks and APIs for real-time event handling.
metadata:
    mintlify-proj: trebleai
    version: "1.0"
---

# Treble AI Skill Reference

## Product Summary

Treble AI is a WhatsApp automation platform that lets you build conversation flows, deploy AI agents, and integrate with CRMs to automate customer interactions at scale. The platform uses a visual conversation editor where you design message flows as decision trees using blocks (message blocks, conditionals, transfers, AI agents). You can deploy conversations via CSV upload, API, or CRM integrations like HubSpot and Salesforce. Key files and concepts: conversations (outbound/inbound flows), blocks (message, conditional, transfer, AI agent), variables (company-provided or customer-collected), templates (HSM—Meta-approved messages), and webhooks for real-time event notifications. Primary docs: https://help.treble.ai

## When to Use

Reach for this skill when:
- **Building conversation flows**: User wants to create automated WhatsApp message sequences with branching logic, options, or conditional routing.
- **Deploying campaigns**: User needs to send outbound messages to customer lists (via CSV, API, or CRM workflow).
- **Creating AI agents**: User wants to build conversational AI that qualifies leads, answers FAQs, collects data, or transfers to humans.
- **Integrating with CRM**: User is connecting Treble to HubSpot, Salesforce, or other systems to sync contacts, properties, or trigger workflows.
- **Handling real-time events**: User needs to configure webhooks to react to message delivery, reads, or platform events.
- **Personalizing messages**: User wants to use variables to customize messages with customer data (name, email, purchase history).
- **Managing agent teams**: User is setting up human handoff, agent assignment rules, or agent workspace configuration.

## Quick Reference

### Core Concepts

| Term | Definition |
|------|-----------|
| **Conversation** | A message flow (campaign) that guides customer interactions. Outbound (company-initiated) or inbound (customer-initiated). |
| **Block** | A single step in a conversation: message, options, conditional, transfer, AI agent, etc. |
| **Variable** | Dynamic data: company-provided ({{customer_name}}) or customer-collected (responses saved as variables). |
| **Template (HSM)** | Meta-approved message used to start outbound conversations. Required for first message in outbound flows. |
| **Webhook** | HTTP POST to your server when events occur (message delivered, read, conversation closed). |
| **AI Agent** | Conversational AI that holds natural dialogue, executes tools (CRM actions, data collection), and escalates to humans. |

### Block Types

| Block | Use Case |
|-------|----------|
| **Template (HSM)** | Start outbound conversations with pre-approved Meta messages. |
| **Simple Message** | Send text; capture free-form responses. |
| **Message with Options** | Display numbered list (unlimited options). |
| **Interactive Buttons** | Show up to 3 quick-reply buttons. |
| **Interactive List** | Show dropdown with up to 10 options. |
| **Conditional** | Route based on variables, native variables, or logic. |
| **Transfer to Agent** | Hand off to human team member. |
| **AI Agent** | Integrate AI agent block into flow. |
| **WhatsApp Flows** | Native interactive forms within WhatsApp. |
| **Jump to Conversation** | Link to another conversation. |
| **A/B Test** | Split traffic between variants to measure performance. |

### API & Webhooks

| Endpoint | Purpose |
|----------|---------|
| **POST /deploy** | Deploy conversation to contacts (phone + country code). Supports scheduling. |
| **GET /convos** | List conversations. |
| **GET /sessions** | Get conversation sessions (interactions). |
| **GET /session-history** | Retrieve message history for a session. |
| **POST /session-update** | Update session variables. |
| **GET /agents** | List agents. |

### Webhook Events

| Event | Trigger |
|-------|---------|
| **message_delivered** | Message sent to WhatsApp. |
| **message_read** | Customer read message. |
| **conversation_closed** | Conversation ended. |
| **hsm_change_state** | Template approval status changed. |
| **deployment_failure** | Conversation send failed. |

### Variable Format

All variables use double-bracket syntax: `{{variable_name}}`

**Company-provided** (set at deploy time):
```
{{customer_name}}, {{email}}, {{last_purchase_date}}
```

**Customer-collected** (saved from responses):
```
{{help_type}}, {{customer_age}}, {{product_interest}}
```

**Native variables** (auto-available, no capture needed):
```
{{country_code}}, {{inbound_message}}, {{current_day}}, {{current_hour}}
```

### Authentication

API key format: `ak_S5BCOgOxrfENbkn-wH2gpPK3AM8ihLNmQg`

Add to request header:
```
Authorization: ak_S5BCOgOxrfENbkn-wH2gpPK3AM8ihLNmQg
```

Obtain from: Settings → Developers → API Key

## Decision Guidance

### When to Use Outbound vs. Inbound

| Scenario | Use |
|----------|-----|
| You initiate contact (promotions, reminders, follow-ups) | **Outbound** (must start with HSM template) |
| Customer initiates contact (support, inquiry, QR code scan) | **Inbound** (no template required) |

### When to Use Each Transfer Method

| Method | When to Use |
|--------|------------|
| **Agent with fewer chats** | Balance load across team. |
| **Random agent** | Even distribution without load tracking. |
| **Specific agent** | Same person always handles this flow. |
| **Owner agent (HubSpot)** | Contact's CRM owner should respond. |
| **Assign to team (HubSpot)** | Any team member can handle. |
| **API** | Your system has custom routing logic. |

### When to Use AI Agent vs. Simple Flow

| Scenario | Use |
|----------|-----|
| Collect structured data, follow rules, execute actions | **AI Agent** (natural conversation, tools, escalation) |
| Simple linear flow with fixed options | **Message blocks** (faster, predictable) |
| Qualify leads, answer FAQs, book appointments | **AI Agent** |
| Send promotional message with one CTA | **Message blocks** |

### When to Deploy Via CSV vs. API vs. CRM

| Method | When to Use |
|--------|------------|
| **CSV upload** | One-time bulk send; data already in spreadsheet. |
| **API** | Automated, real-time sends; integrated with your system. |
| **CRM workflow** | Triggered by HubSpot/Salesforce events (property change, deal stage). |

## Workflow

### Build a Conversation Flow

1. **Define objective**: What should the conversation achieve? (lead qualification, support, promotion, appointment booking)
2. **Choose type**: Outbound (you initiate) or inbound (customer initiates).
3. **Create conversation**: Go to Conversations → Create Conversation.
4. **Add blocks**:
   - Start with HSM template (outbound only).
   - Add message blocks, conditionals, options.
   - Configure variables for personalization and data collection.
5. **Connect blocks**: Drag circles from block outputs to next block inputs.
6. **Test**: Send test message to your WhatsApp number.
7. **Publish**: Click "Create/Publish" button to enable.
8. **Deploy**: Send via CSV, API, or CRM integration.

### Create an AI Agent

1. **Go to AI Agents** section.
2. **Describe what you need**: "Qualify leads, collect name/email/budget, hand off to sales."
3. **Answer generator questions**: Concrete outcomes, data to collect, escalation rules.
4. **Attach files** (optional): PDF catalog, price list, FAQ—mark as "Knowledge base" or "Both."
5. **Review plan**: Confirm the agent's purpose, actions, and constraints.
6. **Configure tools**: Complete pending tool setup (e.g., which team to transfer to).
7. **Test in playground**: Validate behavior before connecting.
8. **Add to conversation**: In Conversation Editor, add AI Agent block (Advanced blocks).
9. **Connect exits**: Define what happens based on agent outcomes (success, escalation, timeout).

### Deploy a Conversation

**Option 1: Manual (small list)**
1. Click "Send" on conversation.
2. Add phone numbers + country codes manually.
3. Fill variable values if needed.
4. Click "Send conversation."

**Option 2: CSV (bulk)**
1. Click "Send" → "Upload file" tab.
2. Download template (includes variable columns).
3. Fill CSV: `country_code | cellphone | {{variable_name}}`
4. Upload file.
5. Choose send time (now or best response time).
6. Click "Send conversation."

**Option 3: API**
1. Get API key from Settings → Developers.
2. POST to `/deploy` endpoint with phone numbers, country codes, variables.
3. Optionally schedule for future date.

**Option 4: CRM Integration**
1. Install HubSpot/Salesforce integration.
2. Create workflow in CRM (e.g., "when deal stage = qualified").
3. Add Treble action: select conversation + WhatsApp number.
4. Publish workflow.

### Configure Webhooks

1. **Go to Settings** → **Webhooks** (or Webhook Center in API Reference).
2. **Add endpoint URL**: Your server endpoint (must respond in <5 seconds, HTTPS recommended).
3. **Select events**: Message delivered, read, conversation closed, HSM state change, etc.
4. **Add auth headers** (optional): JSON with Authorization, X-API-Key, etc.
5. **Save**.
6. **Test**: Trigger event and verify POST received.
7. **Handle in your code**: Parse JSON payload, execute business logic.

## Common Gotchas

- **Outbound must start with HSM**: If you forget the template block, deployment will fail. Always begin outbound flows with a Meta-approved template.
- **Variable names must match CSV columns**: If CSV has "customer_name" but flow uses {{customer_name}}, it works. If CSV has "Name" and flow expects {{customer_name}}, variable stays empty. Download the template CSV to avoid mismatches.
- **Native variables don't need capture**: {{country_code}}, {{inbound_message}}, {{current_hour}} are always available—don't try to save them from user responses.
- **Webhook timeout is 5 seconds**: If your endpoint takes longer, Treble retries. Implement async processing on your end.
- **Conditional blocks need "In all other cases" route**: Never leave the default case unconnected; it will break the flow.
- **AI Agent tools must be configured before publish**: Pending tools (marked yellow) block publication. Complete all tool setup.
- **Transfer to agent requires team/tags**: Ensure agent team exists and is selected in the transfer block.
- **HSM templates need Meta approval**: New templates take time to approve. Test with approved templates first.
- **Variables are case-sensitive**: {{customer_name}} ≠ {{Customer_Name}}.
- **Inbound flows don't use templates**: Inbound conversations start when customer messages you; no HSM needed.
- **A/B test requires both variants**: Don't leave one branch empty.
- **Alternate flow timer can't be 0**: Set minimum 1 minute for timeout redirects.

## Verification Checklist

Before deploying a conversation:

- [ ] **Flow logic**: Walk through happy path and error cases. All branches lead somewhere.
- [ ] **Variables match**: CSV columns match {{variable_names}} in flow (case-sensitive).
- [ ] **Outbound has HSM**: First block is a template (HSM) if outbound.
- [ ] **Conditionals complete**: All conditional blocks have "In all other cases" connected.
- [ ] **Transfer configured**: If using transfer block, team/tags are selected.
- [ ] **AI Agent tools ready**: No yellow "pending" pills in agent instructions.
- [ ] **Test message sent**: Sent test to your WhatsApp number; flow behaves as expected.
- [ ] **Conversation published**: Status shows "Published" (not "No published version").
- [ ] **Contacts ready**: CSV or API payload has valid phone numbers + country codes.
- [ ] **Webhooks tested** (if used): Endpoint received test POST and responded with 200.
- [ ] **Knowledge base uploaded** (if AI agent): Files attached and marked correctly.
- [ ] **Escalation path clear**: Know where conversations go if they timeout or need human help.

## Resources

**Comprehensive navigation**: https://help.treble.ai/llms.txt

**Critical docs**:
- [Conversation Editor](https://help.treble.ai/en/docs/main-platform/conversation-editor) — Visual guide to building flows with blocks.
- [AI Agent Overview](https://help.treble.ai/en/docs/main-platform/ai-center/overview) — How to create and configure AI agents.
- [API Reference](https://help.treble.ai/en/api-reference/intro/intro) — Endpoints, webhooks, authentication.

---

> For additional documentation and navigation, see: https://help.treble.ai/llms.txt