# WhatsApp API Quick Start for Developers Use this guide to add ChatArchitect WhatsApp messaging to any third-party service. It covers credentials, outbound messages, templates, delivery statuses, inbound messages, and a basic test flow.
Agent instruction Copy 
Implement ChatArchitect WhatsApp API connection for this codebase using the official guide:
https://support.chatarchitect.com/books/whatsapp-for-partners/page/whatsapp-api-quick-start-for-developers
Inspect the app’s existing architecture first, then add server-side credential handling, message sending,
template loading, webhook processing for statuses and inbound messages, and minimal UI/settings needed for users to connect.
## What you will build By the end of this guide, your service can: - Send WhatsApp text messages and approved template messages. - Receive asynchronous delivery statuses through a webhook: `submitted`, then `failed`, `sent`, `delivered`, or `read`. - Receive inbound customer messages through the same webhook. - Fetch approved WhatsApp templates from the ChatArchitect API. If a customer writes first, you can reply without a template inside the active customer service window. If your business starts the conversation, use an approved WhatsApp template. ## Prerequisites and credentials The customer must connect WhatsApp Business API through ChatArchitect support and Meta. After setup, ChatArchitect provides: | Credential | Purpose | | --- | --- | | `APP_ID` | Basic Auth username for ChatArchitect API requests. | | `APP_SECRET` | Basic Auth password for ChatArchitect API requests. | Store both values server-side. Do not expose `APP_SECRET` in browser code, public logs, client-side configuration, or URLs. All examples below use: ```text API base URL: https://api.chatarchitect.com Auth: Basic Auth with : Recipient phone: Webhook URL: ``` Use phone numbers in international format without `+`, spaces, or brackets, for example `421233221242`. ## Quick start: 3 API calls ### Step 1 - Register a webhook Register an HTTPS webhook URL for delivery statuses and inbound messages. ```http POST https://api.chatarchitect.com/webhook Authorization: Basic base64(:) Content-Type: application/json ``` Request body: ```json { "channel": "whatsapp", "destination": "", "webhook_separate": "false", "webhook": "" } ``` `destination` can be any WhatsApp number connected to the account. `webhook` must be an HTTPS URL reachable from the public internet. cURL example: ```bash curl -X POST "https://api.chatarchitect.com/webhook" \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "destination": "", "webhook_separate": "false", "webhook": "" }' ``` ### Step 2 - Send a text message Send an outbound WhatsApp message. ```http POST https://api.chatarchitect.com/whatsappmessage Authorization: Basic base64(:) Content-Type: application/json ``` Request body: ```json { "channel": "whatsapp", "destination": "", "payload": { "type": "text", "message": "Hi John, how are you?" } } ``` The synchronous response confirms that the message was accepted into the queue: ```json { "status": "submitted", "messageId": "21110c1d-53e1-42b5-9454-1de9a09d4777" } ``` Final delivery status arrives later through your webhook. cURL example: ```bash curl -X POST "https://api.chatarchitect.com/whatsappmessage" \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "destination": "", "payload": { "type": "text", "message": "Hi John, how are you?" } }' ``` ### Step 3 - Get approved templates Fetch approved WhatsApp templates available for the connected account. ```http POST https://api.chatarchitect.com/getHSM Authorization: Basic base64(:) Content-Type: application/json ``` Request body: ```json { "channel": "whatsapp", "destination": "", "getHSM": "true" } ``` Response fragment: ```json { "status": "submitted", "templates_status": true, "templates": [ { "appId": "abcf5776-29e0-4e3a-a8ed-09c51e69d53e", "category": "MARKETING", "data": "{{26815959-f5b8-49b4-9b0e-7458d34777cc}}\nHello{{1}}" } ] } ``` `templates.data` contains the template send syntax. Store or cache this list in your service so users can select approved templates. cURL example: ```bash curl -X POST "https://api.chatarchitect.com/getHSM" \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "destination": "", "getHSM": "true" }' ``` ## Template rules ### Template types | Type | Use case | | --- | --- | | Text-only | Standard notifications, confirmations, reminders, and updates. | | Media | Messages with text plus an image, video, or document. | For most notifications, text-only templates are enough. ### Template categories | Category | Typical use | | --- | --- | | `MARKETING` | Promotions, offers, reactivation, and other non-transactional messages. | | `UTILITY` | Transactional or service messages without advertising content. | | `OTP` | One-time passwords and verification codes. | Template category affects approval and pricing. Keep promotional content out of `UTILITY` and `OTP` templates. ### Template approval Customers can submit templates through the ChatArchitect application or through ChatArchitect support. If your service needs a deeper integration, you can add template submission through API as a separate feature. ### Template send syntax A template returned by `/getHSM` can look like this: ```text {{26815959-f5b8-49b4-9b0e-7458d34777cc}}\nHello{{1}} ``` Rules: - The first `{{...}}` block is the required template ID. - `{{1}}`, `{{2}}`, and other numbered placeholders are template variables. - Variable values can contain spaces and multiple words. - Variable values must not contain line breaks. To send a template message, use the same `/whatsappmessage` endpoint. The difference from a normal text message is the value of `payload.message`. Example template send body: ```json { "channel": "whatsapp", "destination": "", "payload": { "type": "text", "message": "{{26815959-f5b8-49b4-9b0e-7458d34777cc}}\nHello John" } } ``` ## Webhook events ### Status events Delivery errors are asynchronous. A send request can return `submitted`, while final failure details arrive later in the webhook. Example status event: ```json { "app": "aQWPjCAmjav", "timestamp": 1580311136040, "version": 2, "type": "message-event", "payload": { "id": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35", "type": "failed", "destination": "", "payload": { "code": 1008, "reason": "User is not Opted in and Inactive" } } } ``` Important fields: | Field | Meaning | | --- | --- | | Root `type` | `message-event` for status updates. | | `payload.type` | Final status: `failed`, `sent`, `delivered`, or `read`. | | `payload.destination` | Customer phone number. | | `payload.payload.reason` | Failure reason, present for failed messages when available. | ### Inbound message events Example inbound text message: ```json { "app": "aQWPjCAmjav", "timestamp": 1580227766370, "version": 2, "type": "message", "payload": { "id": "ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c", "source": "", "type": "text", "payload": { "text": "Hi" } } } ``` Important fields: | Field | Meaning | | --- | --- | | Root `type` | `message` for inbound customer messages. | | `payload.source` | Customer phone number. | | `payload.type` | Inbound message type. | | `payload.payload.text` | Text content for text messages. | ### Correlation Store your outbound request metadata together with the synchronous `messageId`. For webhook processing, also use the customer phone number and webhook `payload.id` to match status events and inbound replies to your internal records. ## WhatsApp policy essentials Follow these practical rules when designing messaging in your service: - Send campaigns only to customers who expect messages from the business. - Use approved templates when the business starts the conversation. - Add an unsubscribe option to marketing templates when relevant. - Avoid cold lists. High complaint rates can lead to template restrictions or temporary sending limits. - Keep marketing, utility, and OTP content separated by template category. - Monitor failed deliveries and complaints before increasing volume. ## What to implement in your service A useful integration usually includes these parts: | Feature | Recommended behavior | | --- | --- | | Credentials | Store `APP_ID` and `APP_SECRET` server-side per customer account. | | Template list | Fetch templates from `/getHSM`, show category and text preview, and let users refresh the list. | | Template variables | Detect `{{1}}`, `{{2}}`, and other placeholders and let users map them to service fields. | | Audience selection | Let users select recipients and preview personalized messages before sending. | | Send history | Store outbound request time, synchronous `messageId`, final webhook statuses, and failure reasons. | | Inbound messages | Either route replies to another channel or show them in your own conversation UI. | | Webhook processing | Accept status and inbound events on HTTPS, validate data shape, and process duplicate events safely. | ## Code examples ### cURL - send text ```bash curl -X POST "https://api.chatarchitect.com/whatsappmessage" \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "destination": "", "payload": { "type": "text", "message": "Hi John, how are you?" } }' ``` ### Node.js - send text with fetch ```js const APP_ID = process.env.APP_ID; const APP_SECRET = process.env.APP_SECRET; const auth = Buffer.from(`${APP_ID}:${APP_SECRET}`).toString('base64'); async function sendText(destination, text) { const response = await fetch('https://api.chatarchitect.com/whatsappmessage', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${auth}` }, body: JSON.stringify({ channel: 'whatsapp', destination, payload: { type: 'text', message: text } }) }); if (!response.ok) { throw new Error(`ChatArchitect API error: ${response.status}`); } return response.json(); } sendText('', 'Hi John, how are you?') .then(console.log) .catch(console.error); ``` ### Python - send text with requests ```python import os import requests APP_ID = os.environ["APP_ID"] APP_SECRET = os.environ["APP_SECRET"] response = requests.post( "https://api.chatarchitect.com/whatsappmessage", auth=(APP_ID, APP_SECRET), headers={"Content-Type": "application/json"}, json={ "channel": "whatsapp", "destination": "", "payload": { "type": "text", "message": "Hi John, how are you?", }, }, timeout=30, ) response.raise_for_status() print(response.json()) ``` ## Test checklist Use this checklist before showing the integration to customers: - Register an HTTPS webhook with `/webhook`. - Send a normal text message with `/whatsappmessage`. - Confirm the synchronous response contains `status: submitted`. - Receive a final `message-event` webhook with `failed`, `sent`, `delivered`, or `read`. - Fetch templates with `/getHSM`. - Send one approved template message with a real variable value. - Confirm failed template sends display the webhook failure reason in your service. - Send an inbound WhatsApp message from the customer phone and confirm your webhook receives root `type: message`. ## Customer message handling options | Option | Behavior | Best for | | --- | --- | --- | | Minimal | Ignore inbound messages in your service and route operational replies to another channel such as a help desk, email inbox, or team chat. | Fast launch, notification-only use cases. | | Advanced | Show inbound messages in your service and let users reply without templates when the customer wrote first. | Full conversation workflows. | You can start with the minimal option and add a conversation UI later. ## Partner-facing integration description example Use a short description like this when presenting the feature to your customers: ```text ChatArchitect.com WhatsApp for Send and receive WhatsApp messages directly from . Start conversations with approved WhatsApp templates, receive customer replies, and track delivery statuses automatically through webhooks. ``` Recommended feature bullets: - Incoming and outgoing WhatsApp messages. - Business-initiated messages with approved templates. - Delivery status tracking: sent, delivered, read, and failed. - Template preview and variable mapping. - Optional bulk messaging from your own audience filters. ## Recommended flow ```mermaid sequenceDiagram participant Service as Your service participant CA as ChatArchitect API participant WA as WhatsApp user Service->>CA: POST /webhook CA-->>Service: Webhook saved Service->>CA: POST /getHSM CA-->>Service: Approved templates Service->>CA: POST /whatsappmessage CA-->>Service: status=submitted, messageId CA->>Service: message-event sent/delivered/read/failed WA->>CA: Customer reply CA->>Service: inbound message webhook ```