Overview
Create a new support ticket for a WhatsApp Business API contact. This endpoint initializes a conversation in a specific pipeline stage, optionally sends an initial message, and allows you to set custom metadata for both the contact and ticket. This endpoint is specifically for WhatsApp Business API connections (not WhatsApp Web/QR). Use this when you have an official WhatsApp Business API integration.Use Cases
- Form-triggered Tickets: Create a ticket when a user submits a contact form
- E-commerce Integration: Open tickets for new orders or delivery issues
- Onboarding Workflows: Start onboarding tickets for new customers
- Support Escalation: Programmatically create tickets from other systems
- Event-based Tickets: Create tickets based on user behavior or triggers
- CRM Synchronization: Sync customer issues from external CRM to Vambe
Authentication
This endpoint requires authentication using an API key. Include your API key in the request header:Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
phoneId | number/string | Yes | Your WhatsApp Business API phone ID (numeric) |
WhatsApp Business API: The
phoneId
must be a numeric ID from your
WhatsApp Business API configuration. This is different from WhatsApp Web (QR)
which uses string identifiers.Request Body
Field | Type | Required | Description |
---|---|---|---|
to_phone_number | string | Yes | Contactβs WhatsApp phone number (with country code) |
stage_id | string | Yes | UUID of the pipeline stage where the ticket should start |
contact_name | string | No | Full name of the contact |
email | string | No | Contactβs email address (must be valid email format) |
contact_metadata | object | No | Custom key-value pairs for contact-level data |
ticket_metadata | object | No | Custom key-value pairs for ticket-level data |
integration_data | object | No | Integration-specific data (e.g., external system IDs) |
message | object | No | Optional initial message to send when creating the ticket |
Message Object
When providing an initial message, use this structure:Field | Type | Required | Description |
---|---|---|---|
content | string | No | Text content of the message to send |
templateId | string | No | ID of a template to use (if using smart templates) |
ai_generated | boolean | Yes | Whether the message is AI-generated (true) or manual |
Response Structure
The endpoint returns a success response with the created contact information:Field | Type | Description |
---|---|---|
aiContactId | string (UUID) | Unique identifier of the created or existing contact |
status | string | Status of the operation (always βokβ) |
Example Request
Example Response
Common Use Cases
1. Create Ticket from Contact Form
2. E-commerce Order Ticket
3. Create Ticket Without Initial Message
4. Using Smart Templates
Phone ID Requirements
The
phoneId
in the path must be a numeric ID from your WhatsApp Business
API configuration. This is NOT the phone number itself.- β
Correct:
123456789
(numeric phone ID from WhatsApp Business API) - β Incorrect:
"+56912345678"
(this is the customerβs phone number, not your phone ID) - β Incorrect:
"my-phone-id"
(string identifier - use web-whatsapp endpoint instead)
- Check your WhatsApp Business API configuration
- Look in your Vambe dashboard under WhatsApp channels
- The phone ID is a numeric value assigned by WhatsApp
Phone Number Format
Theto_phone_number
field accepts phone numbers in various formats:
- With country code:
"+56912345678"
(recommended) - String format:
"56912345678"
- Number format:
56912345678
Metadata Best Practices
Contact Metadata
Store information about the person:- Company name
- Industry
- Customer tier/plan
- Account creation date
- Language preference
- Time zone
Ticket Metadata
Store information about this specific ticket:- Issue type/category
- Priority level
- Related order/transaction IDs
- Urgency
- Source (web, mobile, API, etc.)
- Custom fields specific to your workflow
Error Responses
Status Code | Description |
---|---|
400 | Bad Request - Invalid phone number or stage ID |
401 | Unauthorized - Invalid or missing API key |
404 | Not Found - Phone ID doesnβt exist or is not numeric |
500 | Internal Server Error - Something went wrong |
Important Notes
- Phone ID Must Be Numeric: The
phoneId
parameter must be a number, not a string identifier - WhatsApp Business API Only: This endpoint is for official WhatsApp Business API connections
- For WhatsApp Web: Use
POST /api/public/ticket/open/web-whatsapp/{phoneId}
instead - Stage ID: Make sure the
stage_id
exists in your pipelines - use GET /api/public/pipeline to get valid stage IDs - Duplicate Contacts: If a contact with the same phone number already exists, the ticket will be created for that existing contact
- Metadata Flexibility: Both
contact_metadata
andticket_metadata
accept any key-value pairs as objects - AI Processing: When you donβt provide a message, the AI assistant will automatically engage based on your pipeline configuration
- Message vs Template: You can provide either plain
content
or use atemplateId
with variables
What Happens After Creation
- Phone ID Validation: System verifies the phone ID is numeric and exists
- Contact Creation/Update: The system finds or creates a contact with the provided phone number
- Metadata Processing: Contact and ticket metadata are processed and stored
- Stage Assignment: The ticket is placed in the specified pipeline stage
- Message Sending (if provided):
- If
message.content
is provided withouttemplateId
: Sends a plain text message via WhatsApp Business API - If
message.templateId
is provided: Sends a WhatsApp approved template with variables - If no message: AI assistant takes over based on pipeline configuration
- If
- Contact ID Return: You receive the
aiContactId
to track this contact for future operations
WhatsApp Business API vs WhatsApp Web
Feature | WhatsApp Business API (This) | WhatsApp Web (QR) |
---|---|---|
Endpoint | /api/public/ticket/open/whatsapp/ | /api/public/ticket/open/web-whatsapp/ |
Phone ID Format | Numeric (e.g., 123456789 ) | String (e.g., "phone_abc123" ) |
Connection Type | Official API from Meta | QR code connection |
Message Types | Templates and plain text | Plain text only |
Reliability | Higher (official API) | Depends on QR connection |
Scalability | Better for high volume | Limited by QR session |
Related Endpoints
- GET /api/public/pipeline - Get available pipeline stages
- GET /api/public/contact//info - Get ticket and contact info
- POST /api/public/contact//update-metadata - Update contact metadata later
- POST /api/public/ticket/close/contact/ - Close an active ticket
- POST /api/public/ticket/open/web-whatsapp/ - WhatsApp Web version
Complete Workflow Example
Headers
API key needed to authorize the request
Path Parameters
Body
application/json
Response
200
Ticket created successfully