{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","partial","tabs","tab"]},"type":"markdown"},"seo":{"title":"Getting Started","description":"Complete developer documentation for the eCommunicate Omnichannel platform. WhatsApp Cloud, WhatsApp Lite, SMS, Live Chat, and Conversations APIs. Send messages, manage templates, configure webhooks, and build customer engagement at scale.","siteUrl":"https://docs.ecommunicate.co.za","keywords":["eCommunicate API","WhatsApp Business API","SMS API","omnichannel messaging","WhatsApp templates","messaging platform","South Africa messaging API"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide walks you through setting up your eCommunicate integration and sending your first WhatsApp message. You'll go from zero to a delivered message in four steps."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Before you begin"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["eCommunicate account"]}," — contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@ecommunicate.co.za"},"children":["support@ecommunicate.co.za"]}," to get started"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["registered WhatsApp number"]}," (Cloud or Lite)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Developer API key"]}," (a UUID string)"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"server-urls","__idx":1},"children":["Server URLs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose the correct base URL for your channel and environment:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Base URL"},"children":["Base URL"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Channel"},"children":["Channel"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.payless4messaging.com"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WhatsApp Cloud"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.payless4messages.com"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WhatsApp Lite"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-the-system-fits-together","__idx":2},"children":["How the system fits together"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["eCommunicate has two messaging surfaces that share the same WhatsApp number — and which surface a message goes through determines whether agents see it in the live-chat UI."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n Your([\"Your system\"])\n Customer([\"Customer\"])\n\n subgraph eComm[\"eCommunicate platform\"]\n direction LR\n API[\"API Service\"]\n Chat[\"Chat Service\"]\n Bot{{\"Create Chat Participant
or Bot reply\"}}\n API <--> Chat\n Chat --> Bot\n end\n\n Customer <-->|\"messages\"| API\n Your -->|\"Notification/Chat\"| API\n Your -->|\"Agent replies\"| Chat\n API -. \"incoming / status / session / event webhooks\" .-> Your\n Chat -. \"chatbot webhook\" .-> Your\n","diagramHtml":"

eCommunicate platform

messages

Notification/Chat

Agent replies

incoming / status / session / event webhooks

chatbot webhook

Your system

Customer

API Service

Chat Service

Create Chat Participant
or Bot reply

","diagramHtmlDark":"

eCommunicate platform

messages

Notification/Chat

Agent replies

incoming / status / session / event webhooks

chatbot webhook

Your system

Customer

API Service

Chat Service

Create Chat Participant
or Bot reply

"},"children":["flowchart LR\n Your([\"Your system\"])\n Customer([\"Customer\"])\n\n subgraph eComm[\"eCommunicate platform\"]\n direction LR\n API[\"API Service\"]\n Chat[\"Chat Service\"]\n Bot{{\"Create Chat Participant
or Bot reply\"}}\n API <--> Chat\n Chat --> Bot\n end\n\n Customer <-->|\"messages\"| API\n Your -->|\"Notification/Chat\"| API\n Your -->|\"Agent replies\"| Chat\n API -. \"incoming / status / session / event webhooks\" .-> Your\n Chat -. \"chatbot webhook\" .-> Your\n"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Message path"},"children":["Message path"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Reaches customer?"},"children":["Reaches customer?"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Visible in live chat?"},"children":["Visible in live chat?"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notification / chat send"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /whatsapp-api-service/v2/channels/whatsapp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅ Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["❌ No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Agent reply"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /pl4chat-service/api/v2/messages"]}," (with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel: WHATSAPP"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅ Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅ Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inbound customer message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(customer → API Service → Chat Service)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["n/a"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅ Yes — creates a participant or routes to the chatbot"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Notifications don't appear in live chat"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Anything you send through the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["notifications endpoint"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/whatsapp-api-service/v2/channels/whatsapp"]},") is delivered directly to the customer through the API Service — it does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," flow through the chat service, so it will not show up on agent screens or in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/pl4chat-service/api/v2/messages"]}," responses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you need an outbound message to be visible to your live-chat agents, send it through the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["agent reply endpoint"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/pl4chat-service/api/v2/messages"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel: WHATSAPP"]},") instead. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/live-chat"},"children":["Live Chat guide"]}," for the full request shape. (The legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Message/sendMessageWhatsapp"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Message/sendMessageWithAttachment"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Message/getMessagesByChatParticipant"]}," endpoints are deprecated — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/migrations#live-chat-v2"},"children":["Migrations"]},".)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-get-your-api-key","__idx":3},"children":["Step 1: Get your API key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every request to the eCommunicate API requires a Developer Key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retrieve your API key using your account credentials (no existing key required):"]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"cURL","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n \"https://api.payless4messaging.com/payless4messaging-service/WhatsApp/authenticate/retrieveApiKey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"user@example.com\", \"password\": \"your-password\", \"clientRef\": \"CLIENT001\"}'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Node.js","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const response = await fetch(\n 'https://api.payless4messaging.com/payless4messaging-service/WhatsApp/authenticate/retrieveApiKey',\n {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n email: 'user@example.com',\n password: 'your-password',\n clientRef: 'CLIENT001',\n }),\n }\n);\nconst { apiKey } = await response.json();\nconsole.log('Your API key:', apiKey);\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.post(\n \"https://api.payless4messaging.com/payless4messaging-service/WhatsApp/authenticate/retrieveApiKey\",\n json={\n \"email\": \"user@example.com\",\n \"password\": \"your-password\",\n \"clientRef\": \"CLIENT001\",\n },\n)\nprint(\"Your API key:\", response.json()[\"apiKey\"])\n","lang":"python"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Generate a new key:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n \"https://api.payless4messaging.com/payless4messaging-service/WhatsApp/SystemUsers/generateAPIKey\" \\\n -H \"Authorization: YOUR_CURRENT_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Key regeneration"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generating a new key ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["immediately invalidates"]}," the previous one. All integrations using the old key will stop working. Update all your services before or immediately after regeneration."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-choose-your-channel","__idx":4},"children":["Step 2: Choose your channel"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"WhatsApp Cloud","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["WhatsApp Cloud uses Meta's official Cloud API. Messages route through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.payless4messaging.com"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Characteristic"},"children":["Characteristic"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Detail"},"children":["Detail"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Template messages"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for outbound — must be pre-approved by Meta"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Session messages"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free-form text/media within the 24-hour customer service window"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SMS fallback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Automatic fallback when recipient is not on WhatsApp"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate limiting"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Managed by Meta based on your quality rating"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"WhatsApp Lite","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["WhatsApp Lite connects directly via QR code or pairing code. Messages route through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.payless4messaging.com"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Characteristic"},"children":["Characteristic"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Detail"},"children":["Detail"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No template restrictions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send any message at any time"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connection"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["QR code or pairing code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Group management"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create, manage, and message WhatsApp groups"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contact sync"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retrieve synced contacts from the connected device"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Throttling"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configurable message throttling and batch delays"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"SMS","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Direct SMS messaging via the unified endpoint or dedicated SMS channel."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Characteristic"},"children":["Characteristic"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Detail"},"children":["Detail"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["GSM 7-bit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["160 chars/part (153 multipart) — best for English text"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Unicode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["70 chars/part (67 multipart) — for non-Latin characters or emoji"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fallback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Also available as automatic fallback for WhatsApp messages"]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-send-your-first-message","__idx":5},"children":["Step 3: Send your first message"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the unified endpoint to send a WhatsApp notification message:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"cURL","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n \"https://api.payless4messaging.com/whatsapp-api-service/v2/messages\" \\\n -H \"Authorization: $ECOMM_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"channel\": \"WHATSAPP\",\n \"payload\": {\n \"sender\": \"+27123456789\",\n \"templateName\": \"seasonal_promo_text\",\n \"templateId\": \"your-template-uuid\",\n \"messageType\": \"NOTIFICATION\",\n \"messages\": [\n {\n \"recipients\": [{ \"to\": \"+27987654321\", \"customerUserId\": \"ZA.1021033720668862\" }],\n \"components\": [\n { \"type\": \"body\", \"parameters\": [\"John\"] }\n ]\n }\n ]\n }\n }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Node.js","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const API_KEY = process.env.ECOMM_API_KEY;\nconst BASE_URL = 'https://api.payless4messaging.com';\n\nconst response = await fetch(`${BASE_URL}/whatsapp-api-service/v2/messages`, {\n method: 'POST',\n headers: {\n 'Authorization': API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n channel: 'WHATSAPP',\n payload: {\n sender: '+27123456789',\n templateName: 'seasonal_promo_text',\n templateId: 'your-template-uuid',\n messageType: 'NOTIFICATION',\n messages: [\n {\n recipients: [{ to: '+27987654321' }],\n components: [{ type: 'body', parameters: ['John'] }],\n },\n ],\n },\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);\n// { status: \"ACCEPTED\", requestId: \"c3a1f8e2-...\", channel: \"WHATSAPP\" }\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import os\nimport requests\n\nAPI_KEY = os.environ[\"ECOMM_API_KEY\"]\nBASE_URL = \"https://api.payless4messaging.com\"\n\nresponse = requests.post(\n f\"{BASE_URL}/whatsapp-api-service/v2/messages\",\n headers={\n \"Authorization\": API_KEY,\n \"Content-Type\": \"application/json\",\n },\n json={\n \"channel\": \"WHATSAPP\",\n \"payload\": {\n \"sender\": \"+27123456789\",\n \"templateName\": \"seasonal_promo_text\",\n \"templateId\": \"your-template-uuid\",\n \"messageType\": \"NOTIFICATION\",\n \"messages\": [\n {\n \"recipients\": [{\"to\": \"+27987654321\"}],\n \"components\": [{\"type\": \"body\", \"parameters\": [\"John\"]}],\n }\n ],\n },\n },\n)\n\nprint(response.json())\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Java","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"import java.net.URI;\nimport java.net.http.*;\nimport java.net.http.HttpResponse.BodyHandlers;\n\nString API_KEY = System.getenv(\"ECOMM_API_KEY\");\nString BASE_URL = \"https://api.payless4messaging.com\";\nHttpClient client = HttpClient.newHttpClient();\n\nString json = \"\"\"\n {\n \"channel\": \"WHATSAPP\",\n \"payload\": {\n \"sender\": \"+27123456789\",\n \"templateName\": \"seasonal_promo_text\",\n \"templateId\": \"your-template-uuid\",\n \"messageType\": \"NOTIFICATION\",\n \"messages\": [\n {\n \"recipients\": [{ \"to\": \"+27987654321\" }],\n \"components\": [\n { \"type\": \"body\", \"parameters\": [\"John\"] }\n ]\n }\n ]\n }\n }\n \"\"\";\n\nHttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(BASE_URL + \"/whatsapp-api-service/v2/messages\"))\n .header(\"Authorization\", API_KEY)\n .header(\"Content-Type\", \"application/json\")\n .POST(HttpRequest.BodyPublishers.ofString(json))\n .build();\n\nHttpResponse response = client.send(request, BodyHandlers.ofString());\nSystem.out.println(response.body());\n","lang":"java"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Addressing a recipient — phone or BSUID"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every customer has a durable, business-scoped user id (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BSUID"]},", alpha usernames — e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA.1021033720668862"]},") that stays stable for your business even if the customer changes their phone number. Address a recipient by phone (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},"), by BSUID (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]},"), or both — supply at least one. When both are present, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]}," takes precedence and the BSUID rides along as a durable fallback. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The phone number remains the primary identifier today"]}," — store the BSUID now and rely on it as phone numbers become optional."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (202 Accepted):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"status\": \"ACCEPTED\",\n \"message\": \"Request accepted\",\n \"requestId\": \"c3a1f8e2-4b6d-11ee-be56-0242ac120002\",\n \"channel\": \"WHATSAPP\",\n \"timestamp\": \"2026-01-15T10:30:00Z\",\n \"response\": \"Request Accepted for Processing\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Asynchronous processing"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," response means the message is queued for delivery. Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/webhooks"},"children":["Webhooks"]}," or the Message Reports API to track the actual delivery status."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-set-up-webhooks","__idx":6},"children":["Step 4: Set up webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure webhooks to receive delivery receipts and incoming messages in real time:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n \"https://api.payless4messaging.com/payless4messaging-service/WhatsApp/WhatsAppClientWebHook\" \\\n -H \"Authorization: $ECOMM_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"incomingMessageURL\": \"https://yourserver.com/webhooks/incoming\",\n \"statusUpdateURL\": \"https://yourserver.com/webhooks/status\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/webhooks"},"children":["Webhooks guide"]}," for full setup instructions, payload schemas, and handler examples."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":7},"children":["Next steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that you've sent your first message, explore these guides to build out your integration:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Guide"},"children":["Guide"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What you'll learn"},"children":["What you'll learn"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key management and security best practices"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/whatsapp-messaging"},"children":["WhatsApp Messaging"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Templates, media, buttons, carousels, and SMS fallback"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/sms-messaging"},"children":["SMS Messaging"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Direct SMS, encoding, and character limits"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/webhooks"},"children":["Webhooks"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Real-time delivery receipts and incoming messages"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/conversations"},"children":["Conversations"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Persistent conversations beyond the 24-hour window"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/error-handling"},"children":["Error Handling"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Status codes, error format, and troubleshooting"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/rate-limits"},"children":["Rate Limits"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Throughput limits, pagination, and best practices"]}]}]}]}]}]},"headings":[{"value":"Getting Started","id":"getting-started","depth":1},{"value":"Server URLs","id":"server-urls","depth":2},{"value":"How the system fits together","id":"how-the-system-fits-together","depth":2},{"value":"Step 1: Get your API key","id":"step-1-get-your-api-key","depth":2},{"value":"Step 2: Choose your channel","id":"step-2-choose-your-channel","depth":2},{"value":"Step 3: Send your first message","id":"step-3-send-your-first-message","depth":2},{"value":"Step 4: Set up webhooks","id":"step-4-set-up-webhooks","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Getting Started","description":"Set up your eCommunicate integration and send your first message in under 5 minutes.","seo":{"title":"Getting Started"}},"lastModified":"2026-07-16T09:46:36.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/getting-started","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}