WhatsApp Bot

Overview

The WhatsApp Bot integrates with Meta’s WhatsApp Business API to enable automated and manual customer communication. It supports template messages, conversation management, and AI-powered responses.

Template Messages

Send pre-approved templates for notifications

Conversation Inbox

Manage customer conversations in one place

AI Assistant

Automated responses for common inquiries

Request Integration

Link conversations to service requests

How It Works

Template Messages

WhatsApp templates are pre-approved message formats used for business-initiated conversations.

Available Templates

nueva_solicitud_de_servicio

Notifies vendors of new service request assignments.Parameters:

Request ID
Service type
Customer name
Contact phone
Address
Requested delivery date

Button: Link to request details

solicitud_recibida_cliente

Confirms receipt of customer’s service request.Parameters:

Customer name
Request ID
Service type
Requested date
Contact email

Header: Brand logo image

ptar_formulario_enviado

Sends PTAR technical questionnaire link to customer.Parameters:

Customer name
Form URL
Vendor name
Vendor phone

Button: Form link with UUID

solicitud_aprobada_operaciones

Notifies vendor that operations approved a service request.Parameters:

Vendor name
Request ID
Approved delivery date

Button: Link to request details

reasignacion_removida

Alerts vendor that a request was reassigned to someone else.Parameters:

Vendor first name
Request ID
Service type

Sending a Template

Navigate to WhatsApp Section

Access WhatsApp tools from the main menu.

Select Template

Choose from approved templates list.

Add Recipients

Enter phone numbers or select from contacts.

Fill Parameters

Provide values for each template variable.

Send

Messages are dispatched via Meta API.

POST /api/whatsapp/send-template
{
  "templateName": "nueva_solicitud_de_servicio",
  "languageCode": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "123" },
        { "type": "text", "text": "Fumigation" },
        { "type": "text", "text": "John Doe" },
        { "type": "text", "text": "+50212345678" },
        { "type": "text", "text": "123 Main St" },
        { "type": "text", "text": "2024-12-15" }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [
        { "type": "text", "text": "abc-123-uuid" }
      ]
    }
  ],
  "recipients": [
    { "phoneNumber": "+50298765432", "requestId": 123 }
  ]
}

Conversation Management

Viewing Conversations

All WhatsApp conversations are centralized in the inbox:

Conversation List

GET /api/whatsapp/conversations?status=active&limit=50

Displays:

Customer name and phone
Last message preview
Unread count
Assigned agent
Linked service request (if any)

Conversation Detail

GET /api/whatsapp/conversations/:conversationId

Shows:

Full message history
Customer information
Conversation metadata
Assignment status

Conversation Statuses

Active

Ongoing conversations requiring attention or follow-up.

Archived

Resolved but kept for reference. Can be reopened if customer replies.

Closed

Completed and no longer active. Not reopened automatically.

Sending Messages

Manual Reply

Respond to customer messages from the conversation view:

Open Conversation

Click on the conversation in the inbox.

Type Message

Enter your response in the text box.

Send

Message is delivered via WhatsApp Business API.

API call

POST /api/whatsapp/conversations/:conversationId/messages
{
  "content": "Hello! How can I help you today?",
  "messageType": "text"
}

Direct Message

Start a new conversation:

POST /api/whatsapp/send
{
  "phoneNumber": "+50212345678",
  "content": "Thank you for contacting us!",
  "requestId": 123
}

WhatsApp’s 24-hour window applies: You can only send free-form messages within 24 hours of the customer’s last message. After that, use templates.

Assignment and Routing

Assign Conversation

Route conversations to specific agents:

Open Conversation

View the conversation details.

Click 'Assign'

Opens agent selection dialog.

Select Agent

Choose the user to handle this conversation.

Confirm

Conversation moves to agent’s inbox.

PUT /api/whatsapp/conversations/:conversationId/assign
{
  "userId": 456
}

Link to Service Request

Connect a conversation to an existing service request:

PUT /api/whatsapp/conversations/:conversationId/link-request
{
  "requestId": 789
}

This enables:

Viewing conversation from request page
Automatic context in AI responses
Better tracking of customer interactions

Webhook Configuration

The WhatsApp webhook receives events from Meta:

Verification (GET)

GET /api/whatsapp/webhook?hub.mode=subscribe&hub.challenge=xyz&hub.verify_token=YOUR_TOKEN

Meta verifies the webhook URL during setup.

Incoming Events (POST)

POST /api/whatsapp/webhook
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WABA_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { ... },
            "messages": [
              {
                "from": "50212345678",
                "id": "wamid.xyz",
                "timestamp": "1700000000",
                "text": { "body": "Hello" },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

The system automatically:

Creates or updates conversation
Saves the message
Triggers AI response (if enabled)
Sends notifications to assigned agents

AI-Powered Responses

The bot can use GPT-4 to generate contextual responses:

How It Works

Customer sends message
System retrieves conversation history
GPT-4 analyzes message and context
Generates appropriate response
Response is sent to customer
Human agent can review and override

Context Sources

Previous conversation messages
Linked service request details
Customer information from database
Company knowledge base (if configured)

AI responses are marked with a flag. Review important conversations manually.

Message Types

WhatsApp supports various message formats:

Text Messages

Plain text communication. Most common type.

Images

Send or receive photos (e.g., service site images).

Documents

Share PDFs or other files (e.g., quotations).

Interactive Buttons

Template messages with clickable buttons for common actions.

Location

Customer can share their location for service delivery.

Read Receipts

Mark conversations as read:

PUT /api/whatsapp/conversations/:conversationId/read

This:

Updates unread count
Clears notification badge
Tracks agent response time

Best Practices

Respond Quickly

Aim to reply within 1 hour during business hours. Customers expect fast responses on WhatsApp.

Use Templates Wisely

Templates are for business-initiated messages. Use plain messages for ongoing conversations within 24 hours.

Link to Requests

Always link conversations to service requests for better tracking and context.

Assign Strategically

Route conversations to agents familiar with the customer or service type.

Review AI Responses

Check AI-generated messages periodically to ensure quality and accuracy.

Template Approval Process

To create new templates:

Design Template

Create template in Meta Business Manager with:

Template name
Category (marketing, utility, authentication)
Message content with variables
Optional header, footer, buttons

Submit for Review

Meta reviews templates (usually 1-3 business days).

Sync to AmbioSys

Once approved, sync templates:

GET /api/whatsapp/templates

Use in System

Approved templates appear in the template selection dropdown.

Troubleshooting

Template Rejected

Common reasons:

Contains variable in greeting (not allowed in opening)
Uses promotional language in utility template
Formatting issues or special characters

Review Meta’s template guidelines and resubmit.

Message Not Delivered

Check:

Phone number format (+502xxxxxxxx)
WhatsApp Business Account status
Customer blocked the number
24-hour window expired (use template)

Webhook Not Receiving Messages

Verify:

Webhook URL is accessible (HTTPS required)
Verify token matches Meta configuration
Webhook subscriptions include “messages” field

Service Requests

Link WhatsApp conversations to service requests

Customer Management

View customer’s WhatsApp contact information

Get Started

Deployment

Core Features

User Management

Overview

Template Messages

Conversation Inbox

AI Assistant

Request Integration

How It Works

Template Messages

Available Templates

Sending a Template

Conversation Management

Viewing Conversations

Conversation Statuses

Sending Messages

Manual Reply

Direct Message

Assignment and Routing

Assign Conversation

Link to Service Request

Webhook Configuration

Verification (GET)

Incoming Events (POST)

AI-Powered Responses

Message Types

Read Receipts

Best Practices

Template Approval Process

Troubleshooting

Service Requests

Customer Management

Build docs developers (and LLMs) love

Get Started

Deployment

Core Features

User Management

​Overview

Template Messages

Conversation Inbox

AI Assistant

Request Integration

​How It Works

​Template Messages

​Available Templates

​Sending a Template

​Conversation Management

​Viewing Conversations

​Conversation Statuses

​Sending Messages

​Manual Reply

​Direct Message

​Assignment and Routing

​Assign Conversation

​Link to Service Request

​Webhook Configuration

​Verification (GET)

​Incoming Events (POST)

​AI-Powered Responses

​Message Types

​Read Receipts

​Best Practices

​Template Approval Process

​Troubleshooting

​Related Features

Service Requests

Customer Management

Build docs developers (and LLMs) love

Overview

How It Works

Template Messages

Available Templates

Sending a Template

Conversation Management

Viewing Conversations

Conversation Statuses

Sending Messages

Manual Reply

Direct Message

Assignment and Routing

Assign Conversation

Link to Service Request

Webhook Configuration

Verification (GET)

Incoming Events (POST)

AI-Powered Responses

Message Types

Read Receipts

Best Practices

Template Approval Process

Troubleshooting

Related Features