Bevatel Integration Requirement & User Guide

1. Executive Summary

Purpose

This document is the single authoritative reference for everyone involved in planning, selling, and delivering integrations between Bevatel products and third-party systems. It defines exactly what information must be collected before any integration work can begin, and it standardises how that information flows from the Sales team to the Technical/Integration team.

Problem Statement

Bevatel's Sales and Account Management teams routinely receive client requests such as:

*"We want to integrate your AI Agent with our CRM."*

These requests arrive without critical details — which CRM, which module, what API type, who owns the system, what data must flow, and in which direction. The result is:

• Delayed delivery timelines
• Multiple rounds of back-and-forth communication
• Incorrect scope estimations
• Integration failures discovered late in delivery
• Poor client experience

What This Document Solves

2. Integration Overview

Bevatel offers four core products that can be integrated with each other or with external third-party systems:

2.1 Supported Integration Types

Type A — AI Agent ↔ CRM (External or Internal)

The AI Agent listens to or conducts conversations and pushes or pulls structured data from a CRM system. This is the most technically complex integration type.

Examples:

• AI Agent collects caller name, phone, and inquiry → Creates a Lead in Zoho CRM
• AI Agent checks an order status by querying Shopify via API
• AI Agent creates a support ticket in Zendesk after a call ends

Type B — Business Chat ↔ CRM

When a customer sends a WhatsApp message (or any Business Chat channel message), an automated workflow reads or writes data in a CRM.

Examples:

• New WhatsApp message from unknown number → Contact automatically created in HubSpot
• Customer identified by phone number → Existing Zoho Lead returned to agent
• Customer data updated in HubSpot → Synced back to Bevatel contact record (bidirectional)

Type C — Call Center ↔ CRM

Phone calls trigger CRM actions such as creating contacts, logging call details, or screen-popping agent consoles with caller data.

Examples:

• Inbound call → Caller identified → Odoo contact profile displayed to agent
• Call ends → Disposition and call duration logged as a CRM activity
• New call from unknown number → CRM Lead created automatically

Type D — AI Agent ↔ Bevatel Products

The AI Agent operates within the Bevatel ecosystem and exchanges data between Bevatel's own products.

Examples:

• AI Agent (voice) escalates to a live Call Center agent with full conversation context
• AI Agent creates a ticket in Bevatel CRM after a chat session
• AI Agent routes Business Chat conversation to correct queue based on intent

2.2 Integration Matrix

3. Mandatory Discovery Questions

**⚠️ CRITICAL: No integration request may be submitted to the Technical team until ALL fields in this section are completed. Partial submissions will be returned without action.**

3.1 Integration Request Form

Section A — Client Information

Section B — Integration Type & Purpose

Section C — AI Agent Details (Fill only if integration involves an AI Agent)

Section D — Third-Party System / CRM Details

Section E — Data Flow Definition

Section F — Technical & Security Requirements

Section G — Acceptance & Sign-Off

4. Integration Scenarios

The following scenarios are real-world integration patterns Bevatel has delivered or supports. Sales and Account Managers may reference these when discussing options with clients.

Scenario 1 — Business Chat + Zoho CRM (Lead Lookup & Auto-Create)

Business Problem: Sales team using Zoho CRM needs to identify WhatsApp contacts instantly and avoid duplicate leads.

How It Works:

1. Customer sends WhatsApp message to client's Bevatel Business Chat number
2. Bevatel searches Zoho CRM Leads module using the customer's phone number
3. If Lead exists: Returns the Zoho Lead URL directly in the Bevatel agent's console
4. If Lead does not exist: Creates a new Lead in Zoho with name, phone, and source ("Bevatel - WhatsApp"), then returns the new Lead URL

Data Sent to Zoho: Customer phone number, name (if available), source label

Data Received from Zoho: Existing or newly created Lead ID + direct URL

Direction: Two-Way

Trigger: Incoming WhatsApp message

Prerequisites: Zoho CRM API Key, Leads module access, API documentation

Scenario 2 — Business Chat + HubSpot (Auto Contact Creation + Bidirectional Sync)

Business Problem: Client wants all WhatsApp contacts to automatically appear in HubSpot and have data stay in sync.

How It Works:

1. New WhatsApp message arrives
2. Bevatel checks if contact exists in HubSpot by phone number
3. Bevatel creates a new HubSpot Contact with name, phone, and source tag "Bevatel - WhatsApp" if not found
4. Returns the HubSpot Contact URL to the agent
5. When HubSpot agent updates name, email, phone, or status → Bevatel workflow automatically syncs the update back into Bevatel's contact record

Data Sent to HubSpot: Name, phone, source

Data Received from HubSpot: Contact record, contact URL

Direction: Two-Way (bidirectional sync)

Trigger: Inbound message (Bevatel → HubSpot); HubSpot record update (HubSpot → Bevatel)

Scenario 3 — Business Chat + Odoo (Contacts, Leads, Invoice Delivery)

Business Problem: Client runs Odoo as their ERP and needs WhatsApp to act as a customer-facing channel with full CRM awareness.

How It Works:

1. WhatsApp message received → System checks Odoo Contacts by phone number
2. If not found, a new Contact is created in Odoo
3. A Lead is automatically created in Odoo CRM from the WhatsApp conversation
4. Sales team can send an invoice PDF directly from Odoo to the customer's WhatsApp number

Data Sent to Odoo: Phone number, name, source, message content

Data Received from Odoo: Contact profile, Lead ID

Direction: Two-Way

Modules Involved: Contacts, CRM (Leads), Invoicing

Scenario 4 — Business Chat + Zendesk (Automatic Ticket Creation)

Business Problem: Support team needs every WhatsApp inquiry or complaint to become a trackable Zendesk ticket automatically.

How It Works:

1. Customer sends inquiry or complaint via WhatsApp
2. The automated response system captures the message text and phone number
3. A Zendesk ticket is automatically created with the message content, customer phone, and channel source
4. Support team receives the ticket and can respond from Zendesk

Data Sent to Zendesk: Phone number, message text, channel source

Data Received from Zendesk: Ticket ID, ticket URL

Direction: One-Way (Bevatel → Zendesk for ticket creation)

Trigger: Incoming WhatsApp message with inquiry/complaint keyword or bot intent

Scenario 5 — Business Chat + Shopify (E-Commerce Customer Journey Automation)

Business Problem: E-commerce client wants post-purchase communication and cart recovery via WhatsApp.

How It Works:

1. New customer signup → Automatic welcome message sent via WhatsApp
2. Order placed → Order confirmation with order number sent immediately via WhatsApp
3. Order shipped → Shipping tracking link sent automatically
4. Cart abandoned without payment → Reminder message sent via WhatsApp with recovery link
5. Order delivered + 1 day → Instructions or manual sent to customer
6. Customer replies with order number → Bot looks up Shopify order status and returns tracking link

Data Received from Shopify: Order status, order number, tracking link, cart contents, delivery date

Direction: One-Way trigger from Shopify events → Bevatel sends WhatsApp messages

Trigger: Shopify webhooks (order.created, order.fulfilled, cart.abandoned, etc.)

Scenario 6 — Bevatel AI Agent (Voice) + External CRM

Business Problem: Client wants their voice AI Agent to create CRM records automatically after an AI-handled call.

How It Works:

1. Customer calls the client's AI Agent
2. AI Agent conducts the conversation, collects structured data (name, phone, inquiry)
3. After call ends (or at any defined moment), Bevatel AI Agent calls the external CRM's API
4. CRM Lead / Contact / Ticket is created with the collected data
5. Optional: AI Agent queries CRM mid-call for real-time data (e.g., account balance, order status)

Critical Prerequisites:

• AI Agent must be Bevatel-built, OR the client-built AI Agent must expose a SIP Integration
• External CRM must have a REST API
• Authentication credentials (API key / OAuth token) must be provided
• Specific CRM module and field mapping must be defined

Scenario 7 — AI Agent Escalation to Bevatel Call Center

Business Problem: AI Agent reaches conversation limits and needs to transfer to a live human agent with context.

How It Works:

1. AI Agent detects escalation trigger (customer request, complexity, or timeout)
2. AI Agent packages conversation context (summary, customer data, intent)
3. Bevatel routes call or chat to available live agent with full context pre-loaded
4. Live agent sees conversation history and does not ask customer to repeat information

Direction: Internal — AI Agent → Call Center

Trigger: Escalation intent detected by AI

5. Data Flow Definition

Every integration must have a clearly documented data flow. The following framework must be used.

5.1 Core Data Flow Concepts

5.2 Example Data Flow — Business Chat → Zoho CRM

TRIGGER: Incoming WhatsApp message

DATA SENT (Bevatel → Zoho):
  - phone_number: "+966XXXXXXXXX"
  - first_name: "Ahmed"
  - source: "Bevatel - WhatsApp"

LOOKUP LOGIC:
  - Search Zoho Leads by phone_number
  - If FOUND → Return lead_url
  - If NOT FOUND → Create Lead → Return new lead_url

DATA RECEIVED (Zoho → Bevatel):
  - lead_id: "ZCRMxxxx"
  - lead_url: "https://crm.zoho.com/crm/..."

DIRECTION: Two-Way
FREQUENCY: Real-time (per message)

5.3 Example Data Flow — Shopify → Business Chat (Order Confirmation)

TRIGGER: Shopify Webhook — order.created

DATA RECEIVED (Shopify → Bevatel):
  - order_id
  - customer_phone
  - customer_name
  - order_number
  - total_price
  - currency

ACTION: Bevatel sends WhatsApp message to customer_phone

DATA SENT (Bevatel → Customer):
  - WhatsApp message with order confirmation text + order_number

DIRECTION: One-Way (Shopify event → Bevatel → Customer)
FREQUENCY: Real-time, event-driven

5.4 Data Flow Direction Reference

6. Field Mapping Concept

Field mapping is the process of defining which data field in System A corresponds to which field in System B. This is required for every integration and must be confirmed before Technical team can begin development.

6.1 Why Field Mapping Matters

Different systems use different names for the same piece of information:

If field mapping is not declared, data ends up in the wrong field, or the integration fails entirely.

6.2 Field Mapping Template

For each integration, the Account Manager must complete a field mapping table with the client:

6.3 Data Type Rules

7. Technical Requirements

7.1 API Requirements

Every integration with an external system requires the following information to be verified:

7.2 Authentication Methods

**Security Rule:** All API credentials must be stored in Bevatel's secrets management system. Credentials must never be shared via email or chat messages.

7.3 Webhooks

Webhooks allow external systems to push data to Bevatel automatically when events occur (e.g., when an order is created in Shopify).

7.4 Rate Limits Reference

**Action Required:** If expected message volume could approach rate limits, this must be flagged to the Technical team during discovery.

7.5 Security Considerations

8. Common Mistakes & Missing Information

The following table documents the most frequent failures from integration requests submitted without sufficient detail.

8.1 Incomplete Request Examples

8.2 Sales Common Mistakes

8.3 Technical Issues Caused by Missing Information

9. Standard Operating Procedure (SOP)

This SOP defines the mandatory steps from the moment a client requests an integration to the moment the Technical team begins implementation.

9.1 Overview

Client Request → Sales Discovery → Form Completion → AM Review → 
Technical Assessment → Scoping & Estimation → Client Approval → 
Development → Testing → Go-Live

9.2 Step-by-Step Process

Step 1 — Initial Client Request (Sales)

• Owner: Sales Representative
• Actions:

1. Listen to the client's integration request

2. Do NOT make any promises about delivery timeline, cost, or feasibility

3. Explain that a structured discovery process is required

4. Schedule a 30-minute discovery call with the client

• Output: Discovery call scheduled

Step 2 — Discovery Call (Sales + Account Manager)

• Owner: Account Manager (Sales may attend)
• Actions:

1. Use this document's Section 3 (Discovery Questions) as the call agenda

2. Walk through each section with the client

3. Record all answers in the Integration Request Form (digital or PDF)

4. Identify if the client needs to check any answers with their IT team

5. If answers are incomplete, schedule a follow-up session

• Output: Completed Integration Request Form (all sections A through G)

Step 3 — AM Internal Review

• Owner: Account Manager
• Actions:

1. Review the completed form for any missing or inconsistent answers

2. Confirm the client has confirmed access to API keys or OAuth permissions

3. Confirm sandbox environment details are included

4. Cross-check Section B (integration type) matches Sections C, D, E

• Gate: Do not proceed if any required (✅) field is blank
• Output: Validated Integration Request Form

Step 4 — Technical Review & Assessment

• Owner: Integration Engineering Team
• Timeline: Within 2 business days of receiving validated form
• Actions:

1. Review all technical fields (Sections C, D, E, F)

2. Validate API availability by reviewing documentation link

3. Identify technical risks or unknowns

4. Define implementation approach (webhook, REST API polling, workflow engine)

5. Produce a Technical Assessment document with: scope, effort estimate, risks, open questions

• Output: Technical Assessment + Effort Estimate

Step 5 — Scoping & Client Approval

• Owner: Account Manager
• Actions:

1. Receive Technical Assessment from Engineering team

2. Prepare proposal for client including: scope, cost, timeline

3. Confirm delivery timeline only after Engineering estimate is received

4. Obtain client written approval of scope

• Output: Signed scope / confirmed email approval from client

Step 6 — Development

• Owner: Integration Engineering Team
• Actions:

1. Create integration in development/sandbox environment

2. Build data flows according to field mapping (Section 6)

3. Implement error handling as defined in discovery (Section F7, F8)

4. Complete unit testing with sandbox credentials

• Output: Working integration in test environment

Step 7 — UAT (User Acceptance Testing)

• Owner: Account Manager + Client
• Actions:

1. AM coordinates test session with client

2. Client validates each defined scenario works correctly

3. Any issues logged and resolved by Engineering team

4. Signed UAT sign-off from client

• Output: UAT sign-off

Step 8 — Go-Live

• Owner: Integration Engineering Team + Account Manager
• Actions:

1. Engineering switches from sandbox to production credentials

2. Monitor integration for 24–48 hours post go-live

3. AM confirms with client that integration is operational

4. Handover documentation provided to client

• Output: Live integration, handover document

9.3 SOP Summary Table

**Note:** Timelines are estimates for standard integrations. Complex SAP or custom ERP integrations may require 45–90 days.

9.4 Escalation Rules

10. FAQ

Q1: A client says "just connect AI with CRM" — what do I do?

A: This is considered an incomplete request. Tell the client you need to schedule a 30-minute discovery call and that you will send them the Integration Requirement Form to fill before the call. Do not commit to anything or register the request with the Technical team until the form is complete.

Q2: The client says their CRM has an API but they don't have documentation. Can we still start?

A: No. API documentation is mandatory. Without it, the Engineering team cannot define the correct endpoints, request format, response format, or error handling behavior. Ask the client to request API documentation from their CRM vendor. Most enterprise CRMs publish documentation online (e.g., Zoho: developer.zoho.com, HubSpot: developers.hubspot.com).

Q3: Can we integrate with any CRM the client uses?

A: Bevatel can integrate with any CRM or system that offers a REST API with standard authentication. Systems without APIs (e.g., legacy systems with only a desktop UI) cannot be directly integrated without custom middleware — which would require senior Engineering evaluation. Always confirm API availability in Section D of the form.

Q4: What if the client wants one-way sync? Is that simpler?

A: Yes, significantly. One-way integrations (e.g., Bevatel pushes data to CRM only) require no webhook setup on Bevatel's side and less error-handling logic. Always clarify direction in Section E of the form. Two-way sync doubles the complexity and scope.

Q5: The client says the AI Agent was built by a third party and that company will "handle the connection." What does this mean for Bevatel?

A: If a third-party built the AI Agent, Bevatel still needs to understand how the AI Agent communicates with Bevatel's systems. Ask:

• Does the third-party AI Agent expose a REST API that Bevatel can call?
• Does it support incoming webhooks from Bevatel?
• Who provides API documentation and credentials?

Bevatel cannot integrate with a "black box" system.

Q6: What if the client is on a CRM free plan that doesn't include API access?

A: The client must upgrade their CRM plan to one that includes API access before any integration can proceed. This is the client's responsibility. Bevatel can advise on which plan tier typically includes API access for common CRMs:

• Zoho CRM: Standard plan and above
• HubSpot: Starter and above
• Zendesk: Suite Team and above
• Odoo: All plans (self-hosted or cloud)
• Shopify: All plans include API access

Q7: What is a sandbox environment and why is it required?

A: A sandbox is a test version of a system that is isolated from production data. It is required because:

1. Integration testing on production systems can corrupt real client data
2. API errors in production affect real customers
3. Bevatel Engineering must test all scenarios before go-live

Any client refusing to provide sandbox credentials must be informed of the risk and provide written acceptance if they insist on production-only testing.

Q8: Can Bevatel AI Agent query a CRM mid-call in real time?

A: Yes, but this requires the CRM to return responses within 2–3 seconds. Slow APIs cause voice pauses that degrade the customer experience. The Engineering team must test response times in the sandbox before committing to this scenario. This must be noted in Section D of the requirement form.

Q9: How long does a typical integration take to deliver?

A: Standard integrations (Business Chat ↔ Known CRM like Zoho, HubSpot, Odoo) typically take 10–15 business days from receiving a validated requirement form. Complex integrations (AI Agent ↔ Custom ERP, SAP, multi-module bidirectional sync) can take 30–90 days. Do not quote timelines to clients before receiving the Technical Assessment from Engineering.

Q10: Do we support integrations with WhatsApp directly (without Business Chat)?

A: Bevatel Business Chat uses the official WhatsApp Business API. Any WhatsApp integration is therefore delivered through Business Chat. If a client has their own WhatsApp Business API account and wants to connect it to Bevatel, this is a separate technical discussion — escalate to the Product team.

Appendix A — Glossary

Appendix B — Quick Reference Card (For Sales Team)

Print or share this section with the Sales team for use during initial client calls.

Before You Promise Anything, Ask These 5 Questions:

1. Which Bevatel product is involved? (Business Chat / Call Center / CRM / AI Agent)
2. Which external system do they want to connect? (Zoho / HubSpot / Odoo / Custom / Other — get the exact name and version)
3. Does that system have an API? (Ask: "Does your current plan include API access?")
4. What should happen when a specific event occurs? (e.g., "When a customer sends a WhatsApp message, what do you want to happen in your CRM?")
5. What data should move, and in which direction? (Bevatel to CRM, CRM to Bevatel, or both?)

Document maintained by Bevatel Product & Integration Team. For updates or corrections, contact the Integration Manager.

Version 1.0 — April 2026
Mohamed Elnagar