SARAH
DocumentationAPI Reference

WhatsApp

Guide to integrate WhatsApp with Sarah using AI assistant

Last updated: 2025-01-26

Sarah includes an AI assistant integrated with WhatsApp that allows your customers to query products, place orders, and get support directly from WhatsApp.

Features

  • 🤖 AI Assistant: Responds to queries using artificial intelligence
  • 📦 Product Queries: Customers can search products by name or code
  • 🛒 Order Creation: Customers can build orders directly via WhatsApp
  • 📊 Data Access: Assistant can query sales, products, stock, etc.
  • 🎯 Multi-company: Supports customers who are contacts of multiple companies
  • 💬 Conversation Context: Maintains context from previous conversations

Initial Configuration

1. Configure Twilio

Sarah uses Twilio to connect with WhatsApp. You need:

  1. Create an account on Twilio
  2. Configure a WhatsApp number in Twilio
  3. Get your credentials:
    • TWILIO_ACCOUNT_SID
    • TWILIO_AUTH_TOKEN
    • TWILIO_NUMBER

2. Configure in Sarah

  1. Log in to Sarah
  2. Go to Settings > Integrations > WhatsApp
  3. Enter your Twilio credentials
  4. Configure your company's WhatsApp number
  5. Save configuration

3. Configure Webhook

In Twilio, configure webhook to receive messages:

  1. Go to Messaging > Settings > WhatsApp Sandbox (or production configuration)
  2. Configure webhook URL: https://sarah.ar/api/whatsapp
  3. Select method: POST

Functionalities

Product Queries

Customers can search products:

Query examples:

  • "Do you have product X?"
  • "I'm looking for code 12345"
  • "How much does product Y cost?"
  • "Do you have stock of Z?"

Assistant response:

Yes, we have [Product X] available.
Price: $1,500.00
Stock: 10 units
Code: ABC-001

Order Creation

Customers can build orders directly:

Conversation example:

Customer: I want 2 units of product ABC-001
Assistant: Perfect, I added 2 units of [Product] to your order.
          Partial total: $3,000.00
          Would you like to add anything else?

Customer: No, that's all
Assistant: Your order is ready:
          - 2x [Product] = $3,000.00
          Total: $3,000.00
          Do you confirm the order?

Sales Queries

Customers can query their sales:

Examples:

  • "What are my latest purchases?"
  • "How much did I spend this month?"
  • "Do I have any pending sale?"

Support

Assistant can help with problems:

Example:

Customer: I have a problem with my order
Assistant: I'm sorry to hear that. Could you tell me more details?
          [Assistant tries to resolve or escalates to human support]

User Types

Company Owners

If WhatsApp number matches the one configured in companies.whatsapp_ai:

  • Full access to company data
  • Can query sales, products, stock, etc.
  • Can receive technical support

Registered Contacts

If number belongs to a contact in contacts:

  • Can query products from companies where they're a contact
  • Can create orders
  • If contact of multiple companies, can choose which one to interact with

Selection example:

Assistant: I see you're a contact of several companies:
          1. Company A
          2. Company B
          Which one do you want to talk to today?

Prospects

If number is not registered:

  • Receives general information about Sarah
  • Can be converted to contact
  • No access to specific data

Webhook

Endpoint

POST /api/whatsapp

Request Structure

Twilio sends a FormData with:

javascript
{
  "From": "whatsapp:+5491150999958",
  "Body": "Hello, I want to query products",
  "MessageSid": "SM1234567890"
}

Processing

  1. Normalization: Number is normalized (removes whatsapp:+)
  2. Company Search: Searches if number corresponds to a company
  3. Contact Search: If not company, searches in contacts
  4. Response Generation: AI assistant generates a response
  5. Send: Response is sent via WhatsApp

Response

Sarah responds with a text message:

xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Message>Assistant response</Message>
</Response>

AI Assistant

Model

Sarah uses Google Gemini 2.5 Flash Lite to generate responses.

Context

Assistant has access to:

  • Database: Can query products, sales, stock, etc.
  • Previous conversations: Maintains context from last messages
  • Company information: Knows company data and products
  • Specific instructions: Follows personalized instructions

Available Tools

Assistant can use:

  • Database Operation: Query and modify data in database
  • Product Search: Search products by name or code
  • Sales Query: Query customer sales
  • Order Creation: Create orders (sales) from conversation

System Prompt Example

You are Sarah, assistant of [Company Name].
You're talking with [Customer Name].

INSTRUCTIONS:
- Respond in a friendly and professional manner
- You can query products, create orders, etc.
- Use customer name when appropriate
- If you can't resolve something, offer to escalate to support

TONE:
- Cordial but professional
- Occasional emojis to make it friendlier
- Concise but complete responses

Escalation to Support

If assistant detects a problem requiring human attention:

  1. Tries to resolve: First tries to resolve with AI
  2. Detects need: Identifies if escalation is required
  3. Sends email: Notifies support team
  4. Informs customer: Tells customer they will be contacted

Example:

Customer: My invoice has an error
Assistant: I've analyzed your problem but need to escalate it to the support team.
          A representative will review your case and contact you soon.

Advanced Configuration

Customize Instructions

You can customize assistant behavior by editing instructions in code (requires development).

Configure Support Email

Configure SUPPORT_EMAIL in environment variables to receive escalation notifications.

Development Mode

In development, messages are not actually sent via WhatsApp, only logged.

Security

Origin Validation

Sarah validates that webhooks come from Twilio (requires additional configuration).

Sensitive Data

  • Phone numbers are normalized before storing
  • Conversations are saved in database for context
  • Company data is only accessible to authorized users

Troubleshooting

Messages don't arrive

  1. Verify webhook: Ensure it's configured in Twilio
  2. Review logs: Look for errors in processing
  3. Verify credentials: Ensure Twilio credentials are correct

Assistant doesn't respond correctly

  1. Review context: Verify customer is registered correctly
  2. Verify permissions: Ensure customer has access to data
  3. Review logs: Look for errors in response generation

Orders don't create

  1. Verify customer: Must be registered contact
  2. Review logs: Look for errors in order creation
  3. Verify products: Ensure products exist and have stock

Best Practices

  1. Register contacts: Ensure customers are in contacts
  2. Keep products updated: Assistant queries data in real time
  3. Review conversations: Monitor conversations to improve
  4. Configure support: Ensure you have a support email configured
  5. Customize instructions: Adjust behavior according to your business

Additional Resources

Support

If you need help:

  1. Review conversation logs
  2. Verify configuration in Twilio and Sarah
  3. Contact Sarah support with error details
    WhatsApp - Sarah - Documentación