{ "info": { "_postman_id": "00000000-0000-4000-8000-000000000001", "name": "WhatsApp Gateway API", "description": "Postman collection for WhatsApp Gateway API v1. Use it for transactional, operational, support, internal, and authentication-style messaging. Marketing, cold outreach, and bulk campaigns are not allowed.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "base_url", "value": "https://evoapi.faisak.com", "type": "string" }, { "key": "api_key", "value": "wg_live_replace_with_your_key", "type": "string" }, { "key": "instance_id", "value": "demo-support-line", "type": "string" }, { "key": "phone", "value": "+9665XXXXXXX", "type": "string" }, { "key": "threecx_integration_id", "value": "1", "type": "string" }, { "key": "threecx_secret", "value": "replace_with_3cx_webhook_secret", "type": "string" }, { "key": "webhook_signing_secret", "value": "replace_with_customer_webhook_signing_secret", "type": "string" }, { "key": "timestamp", "value": "2026-05-08T10:00:00Z", "type": "string" } ], "item": [ { "name": "Environment Setup", "description": "Start here. Replace collection variables with values from your WhatsApp Gateway dashboard before sending requests.", "item": [ { "name": "How to configure variables", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/docs/openapi", "host": [ "{{base_url}}" ], "path": [ "docs", "openapi" ] }, "description": "Open the OpenAPI documentation page. Configure collection variables for base_url, api_key, instance_id, phone, threecx_integration_id, threecx_secret, webhook_signing_secret, and timestamp." } } ] }, { "name": "Authentication", "description": "Customer API requests use an API key from the dashboard as a Bearer token.", "item": [ { "name": "GET OpenAPI Spec", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/openapi.json", "host": [ "{{base_url}}" ], "path": [ "openapi.json" ] }, "description": "Fetch the public OpenAPI v1 specification." } } ] }, { "name": "Send Message", "description": "Examples for allowed message purposes. Requests require Content-Type: application/json and Authorization: Bearer {{api_key}}.", "item": [ { "name": "Send transactional message", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"{{instance_id}}\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Your order has shipped.\",\n \"message_purpose\": \"transactional\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Expected success response includes success, status, message_id, and log_id." } }, { "name": "Send support message", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"{{instance_id}}\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Your support request has been updated.\",\n \"message_purpose\": \"support\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Support messages should be expected and tied to a legitimate customer support workflow." } }, { "name": "Send authentication message", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"{{instance_id}}\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Your verification code is 123456.\",\n \"message_purpose\": \"authentication\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Authentication-style examples should use demo codes only in shared workspaces." } } ] }, { "name": "Error Scenarios", "description": "Examples for common public API errors. Some scenarios depend on account state, plan limits, or recipient status.", "item": [ { "name": "Missing API key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"{{instance_id}}\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Your order has shipped.\",\n \"message_purpose\": \"transactional\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Expected error: invalid_api_key." } }, { "name": "Invalid API key", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer wg_live_bad", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"{{instance_id}}\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Your order has shipped.\",\n \"message_purpose\": \"transactional\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Expected error: invalid_api_key." } }, { "name": "Blocked marketing purpose", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"{{instance_id}}\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Limited time promotion.\",\n \"message_purpose\": \"marketing\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Expected error: message_purpose_not_allowed." } }, { "name": "Wrong instance", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"wrong-instance\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Your order has shipped.\",\n \"message_purpose\": \"transactional\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Expected error: invalid_instance." } }, { "name": "Module not enabled example", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"{{instance_id}}\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Your order has shipped.\",\n \"message_purpose\": \"transactional\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Expected error: module_not_enabled when API Access is disabled for the account, plan, or customer override." } }, { "name": "Suppressed recipient example", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instance_id\": \"{{instance_id}}\",\n \"phone\": \"{{phone}}\",\n \"message\": \"Your support request has been updated.\",\n \"message_purpose\": \"support\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/send-message", "host": [ "{{base_url}}" ], "path": [ "api", "send-message" ] }, "description": "Expected error: recipient_suppressed if the recipient has opted out or is suppressed by policy." } } ] }, { "name": "Customer Webhook Examples", "description": "Example-only payloads a customer webhook receiver may receive. Send these to a private testing endpoint such as webhook.site.", "item": [ { "name": "message.received example", "request": { "method": "POST", "header": [ { "key": "X-WhatsApp-Gateway-Event", "value": "message.received", "type": "text" }, { "key": "X-WhatsApp-Gateway-Timestamp", "value": "{{timestamp}}", "type": "text" }, { "key": "X-WhatsApp-Gateway-Signature", "value": "sha256=example_signature", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"message.received\",\n \"instance_id\": \"{{instance_id}}\",\n \"instance_name\": \"Demo Support Line\",\n \"from\": \"{{phone}}\",\n \"message_text\": \"Hello, I need help with my order.\",\n \"message_type\": \"text\",\n \"external_message_id\": \"wamid.example\",\n \"timestamp\": \"{{timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://webhook.site/replace-with-your-test-url", "protocol": "https", "host": [ "webhook", "site" ], "path": [ "replace-with-your-test-url" ] }, "description": "Example customer webhook payload for an inbound received message." } }, { "name": "recipient.opted_out example", "request": { "method": "POST", "header": [ { "key": "X-WhatsApp-Gateway-Event", "value": "recipient.opted_out", "type": "text" }, { "key": "X-WhatsApp-Gateway-Timestamp", "value": "{{timestamp}}", "type": "text" }, { "key": "X-WhatsApp-Gateway-Signature", "value": "sha256=example_signature", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"recipient.opted_out\",\n \"instance_id\": \"{{instance_id}}\",\n \"instance_name\": \"Demo Support Line\",\n \"from\": \"{{phone}}\",\n \"reason\": \"recipient_requested_stop\",\n \"message_text\": \"STOP\",\n \"timestamp\": \"{{timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://webhook.site/replace-with-your-test-url", "protocol": "https", "host": [ "webhook", "site" ], "path": [ "replace-with-your-test-url" ] }, "description": "Example customer webhook payload when a recipient sends an opt-out keyword." } }, { "name": "message.sent example", "request": { "method": "POST", "header": [ { "key": "X-WhatsApp-Gateway-Event", "value": "message.sent", "type": "text" }, { "key": "X-WhatsApp-Gateway-Timestamp", "value": "{{timestamp}}", "type": "text" }, { "key": "X-WhatsApp-Gateway-Signature", "value": "sha256=example_signature", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"message.sent\",\n \"instance_id\": \"{{instance_id}}\",\n \"instance_name\": \"Demo Support Line\",\n \"to\": \"{{phone}}\",\n \"message_id\": \"wamid.example\",\n \"message_purpose\": \"transactional\",\n \"timestamp\": \"{{timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://webhook.site/replace-with-your-test-url", "protocol": "https", "host": [ "webhook", "site" ], "path": [ "replace-with-your-test-url" ] }, "description": "Example customer webhook payload after an outbound message is accepted by the gateway send flow." } }, { "name": "message.failed example", "request": { "method": "POST", "header": [ { "key": "X-WhatsApp-Gateway-Event", "value": "message.failed", "type": "text" }, { "key": "X-WhatsApp-Gateway-Timestamp", "value": "{{timestamp}}", "type": "text" }, { "key": "X-WhatsApp-Gateway-Signature", "value": "sha256=example_signature", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"message.failed\",\n \"instance_id\": \"{{instance_id}}\",\n \"instance_name\": \"Demo Support Line\",\n \"to\": \"{{phone}}\",\n \"message_id\": \"wamid.example\",\n \"message_purpose\": \"support\",\n \"error_code\": \"gateway_send_failed\",\n \"error_message\": \"The message passed responsible messaging checks, but delivery could not be completed.\",\n \"timestamp\": \"{{timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://webhook.site/replace-with-your-test-url", "protocol": "https", "host": [ "webhook", "site" ], "path": [ "replace-with-your-test-url" ] }, "description": "Example customer webhook payload after an attempted delivery failure." } } ] }, { "name": "Webhook Signature Verification", "description": "Customer webhook receivers can verify event authenticity with the signing secret shown once in the dashboard.", "item": [ { "name": "Signature formula", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/docs/receive", "host": [ "{{base_url}}" ], "path": [ "docs", "receive" ] }, "description": "Signature formula: hmac_hex = HMAC_SHA256(timestamp + \".\" + raw_body, webhook_signing_secret), then X-WhatsApp-Gateway-Signature = sha256=. Example Postman JavaScript: const rawBody = pm.request.body ? pm.request.body.raw : ''; const base = pm.variables.get('timestamp') + '.' + rawBody; const signature = 'sha256=' + CryptoJS.HmacSHA256(base, pm.variables.get('webhook_signing_secret')).toString();" } } ] }, { "name": "3CX Middleware", "description": "Examples for the 3CX Middleware webhook. Keep 3CX secrets private and rotate them if exposed.", "item": [ { "name": "3CX test event", "request": { "method": "POST", "header": [ { "key": "X-WhatsApp-Gateway-3CX-Secret", "value": "{{threecx_secret}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event_type\": \"test\",\n \"event_id\": \"evt_demo_test\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/integrations/3cx/webhook/{{threecx_integration_id}}", "host": [ "{{base_url}}" ], "path": [ "integrations", "3cx", "webhook", "{{threecx_integration_id}}" ] }, "description": "Expected success if the integration exists, webhook secret is valid, and 3CX Middleware is enabled." } }, { "name": "3CX outbound_message event", "request": { "method": "POST", "header": [ { "key": "X-WhatsApp-Gateway-3CX-Secret", "value": "{{threecx_secret}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event_type\": \"outbound_message\",\n \"to\": \"{{phone}}\",\n \"message_text\": \"Your support request has been updated.\",\n \"message_purpose\": \"support\",\n \"conversation_id\": \"3cx-chat-123\",\n \"agent_extension\": \"101\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/integrations/3cx/webhook/{{threecx_integration_id}}", "host": [ "{{base_url}}" ], "path": [ "integrations", "3cx", "webhook", "{{threecx_integration_id}}" ] }, "description": "Sends a support-purpose WhatsApp message through the configured 3CX integration when allowed." } }, { "name": "3CX missed_call event", "request": { "method": "POST", "header": [ { "key": "X-WhatsApp-Gateway-3CX-Secret", "value": "{{threecx_secret}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event_type\": \"missed_call\",\n \"customer_phone\": \"{{phone}}\",\n \"agent_extension\": \"101\",\n \"queue\": \"Support\",\n \"call_time\": \"2026-05-08T10:00:00Z\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/integrations/3cx/webhook/{{threecx_integration_id}}", "host": [ "{{base_url}}" ], "path": [ "integrations", "3cx", "webhook", "{{threecx_integration_id}}" ] }, "description": "Example call-event payload for a missed call workflow." } } ] } ] }