{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/whatsapp.getokta.io" } ], "info": { "name": "Okta WhatsApp API Documentation", "_postman_id": "f0b95ad9-9e39-4797-88d4-8a84f49ee8f9", "description": "", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Channels", "description": "\nRead-only listing of the WhatsApp channels connected to the active\norganization. Provisioning happens in the admin UI; the API only\nsurfaces the connected channels so callers can pick one for outbound\nsends.", "item": [ { "name": "List channels", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/channels", "query": [], "raw": "{{baseUrl}}\/api\/v1\/channels" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": \"01HZK7P5R3Q6V0YH4XJ3M8CHN1\",\n \"type\": \"cloud\",\n \"status\": \"connected\",\n \"display_name\": \"Sales line\",\n \"phone_number\": \"+966500000000\",\n \"connected_at\": \"2026-05-01T08:00:00+00:00\",\n \"last_seen_at\": \"2026-05-06T10:21:00+00:00\"\n }\n ]\n}", "name": "" } ] }, { "name": "Get a channel", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/channels\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/channels\/:id", "variable": [ { "id": "id", "key": "id", "value": "01HZK7P5R3Q6V0YH4XJ3M8CHN1", "description": "Channel ULID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "permissions-policy", "value": "geolocation=(), microphone=(), camera=()" }, { "key": "strict-transport-security", "value": "max-age=63072000; includeSubDomains; preload" }, { "key": "access-control-allow-origin", "value": "*" } ], "code": 401, "body": "{\"message\":\"Unauthenticated.\"}", "name": "" } ] } ] }, { "name": "Contacts", "description": "\nManage WhatsApp contacts inside the authenticated organization.", "item": [ { "name": "List contacts", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contacts", "query": [ { "key": "search", "value": "ali", "description": "Filter by name, phone, or wa_id (substring).", "disabled": false }, { "key": "per_page", "value": "50", "description": "Page size, between 1 and 100. Defaults to 25.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number. Defaults to 1.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/contacts?search=ali&per_page=50&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a paginated list of contacts in the active organization,\nordered by most recently created first." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": \"01HZK7P5R3Q6V0YH4XJ3M8AAA1\",\n \"wa_id\": \"966500000000\",\n \"phone\": \"+966500000000\",\n \"name\": \"Ali\",\n \"email\": null,\n \"language\": \"ar\",\n \"last_seen_at\": \"2026-05-06T10:21:00+00:00\",\n \"created_at\": \"2026-05-01T08:00:00+00:00\"\n }\n ],\n \"meta\": {\"current_page\": 1, \"per_page\": 25, \"total\": 1}\n}", "name": "" } ] }, { "name": "Get a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contacts\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contacts\/:id", "variable": [ { "id": "id", "key": "id", "value": "01HZK7P5R3Q6V0YH4XJ3M8AAA1", "description": "The contact ULID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "permissions-policy", "value": "geolocation=(), microphone=(), camera=()" }, { "key": "strict-transport-security", "value": "max-age=63072000; includeSubDomains; preload" }, { "key": "access-control-allow-origin", "value": "*" } ], "code": 401, "body": "{\"message\":\"Unauthenticated.\"}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\": \"No query results for model [Contact].\"}", "name": "" } ] }, { "name": "Create or update a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contacts", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contacts" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"wa_id\":\"966500000000\",\"phone\":\"+966500000000\",\"name\":\"Ali\",\"email\":\"ali@example.com\",\"language\":\"ar\",\"profile\":[],\"custom_fields\":[]}" }, "description": "Idempotent on (organization, wa_id). Existing contact attributes are\noverwritten by the values you send \u2014 omit a field to leave it untouched." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": \"01HZK7P5R3Q6V0YH4XJ3M8AAA1\",\n \"wa_id\": \"966500000000\",\n \"phone\": \"+966500000000\",\n \"name\": \"Ali\",\n \"email\": null,\n \"language\": \"ar\"\n }\n}", "name": "" } ] } ] }, { "name": "Conversations", "description": "", "item": [ { "name": "List conversations", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/conversations", "query": [ { "key": "status", "value": "open", "description": "Filter by status (open, pending, snoozed, closed).", "disabled": false }, { "key": "channel_id", "value": "01HZK7P5R3Q6V0YH4XJ3M8CHN1", "description": "Filter by channel ULID.", "disabled": false }, { "key": "per_page", "value": "25", "description": "1-100, defaults to 25.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/conversations?status=open&channel_id=01HZK7P5R3Q6V0YH4XJ3M8CHN1&per_page=25" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Sorted by `last_message_at` descending so the freshest activity\nappears first." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": \"01HZK7P5R3Q6V0YH4XJ3M8CONV1\",\n \"status\": \"open\",\n \"priority\": \"normal\",\n \"unread_count\": 2,\n \"channel_id\": \"01HZK7P5R3Q6V0YH4XJ3M8CHN1\",\n \"contact_id\": \"01HZK7P5R3Q6V0YH4XJ3M8AAA1\",\n \"last_message_at\": \"2026-05-06T10:21:00+00:00\"\n }\n ]\n}", "name": "" } ] }, { "name": "Get a conversation", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/conversations\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/conversations\/:id", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "Conversation ULID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "permissions-policy", "value": "geolocation=(), microphone=(), camera=()" }, { "key": "strict-transport-security", "value": "max-age=63072000; includeSubDomains; preload" }, { "key": "access-control-allow-origin", "value": "*" } ], "code": 401, "body": "{\"message\":\"Unauthenticated.\"}", "name": "" } ] }, { "name": "List messages in a conversation", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/conversations\/:id\/messages", "query": [ { "key": "per_page", "value": "50", "description": "1-100, defaults to 50.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/conversations\/:id\/messages?per_page=50", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "Conversation ULID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Newest first." }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "permissions-policy", "value": "geolocation=(), microphone=(), camera=()" }, { "key": "strict-transport-security", "value": "max-age=63072000; includeSubDomains; preload" }, { "key": "access-control-allow-origin", "value": "*" } ], "code": 401, "body": "{\"message\":\"Unauthenticated.\"}", "name": "" } ] } ] }, { "name": "Embed widget", "description": "\nServer-side API for the embed SDK. The host app (e.g. a Laravel back-end)\ncalls this to mint a short-lived signed token for the current visitor,\nthen hands the token to the browser, which passes it to OktaWa.boot({ token }).\n\nThe token carries the visitor's external reference + optional context\nclaims, so the embedded widget knows who it's talking to without ever\nexposing the org-side signing secret to the browser.", "item": [ { "name": "Mint a signed widget token", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/embed-tokens", "query": [], "raw": "{{baseUrl}}\/api\/v1\/embed-tokens" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"slug\":\"marketing-site\",\"subject\":\"user-12345\",\"context\":[],\"ttl_seconds\":900}" }, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"token\": \"eyJpc3MiOi...\",\n \"expires_in\": 900,\n \"slug\": \"marketing-site\"\n }\n}", "name": "" } ] } ] }, { "name": "Endpoints", "description": "", "item": [ { "name": "POST api\/integrations\/meta\/embedded-signup", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/integrations\/meta\/embedded-signup", "query": [], "raw": "{{baseUrl}}\/api\/integrations\/meta\/embedded-signup" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"code\":\"b\",\"waba_id\":\"n\"}" }, "description": "" }, "response": [] }, { "name": "POST api\/webhooks\/neoleap", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/webhooks\/neoleap", "query": [], "raw": "{{baseUrl}}\/api\/webhooks\/neoleap" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] } ] }, { "name": "Messages", "description": "\nPublic API surface for sending messages from external apps.\n\nThe integrating app provides a destination wa_id (or the ulid of an\nexisting conversation) and the message body. We resolve \/ create the\nContact + Conversation as needed, then hand off to SendMessageAction\nwhich queues the actual provider call.", "item": [ { "name": "Send a message", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/messages", "query": [], "raw": "{{baseUrl}}\/api\/v1\/messages" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"channel_id\":\"01HZK7P5R3Q6V0YH4XJ3M8CHN1\",\"conversation_id\":\"01HZK7P5R3Q6V0YH4XJ3M8CONV1\",\"wa_id\":\"966500000000\",\"type\":\"text\",\"body\":\"Your order is on the way!\",\"media_url\":\"https:\\\/\\\/cdn.example.com\\\/file.pdf\"}" }, "description": "Send a free-form text or media message to a wa_id (auto-creates the\ncontact + conversation if needed) or into an existing conversation\nvia `conversation_id`. The message is queued; the response carries\nthe queued message resource \u2014 poll `GET \/conversations\/{id}\/messages`\nor subscribe to a webhook to track delivery status." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": \"01HZK7P5R3Q6V0YH4XJ3M8MSG1\",\n \"conversation_id\": \"01HZK7P5R3Q6V0YH4XJ3M8CONV1\",\n \"channel_id\": \"01HZK7P5R3Q6V0YH4XJ3M8CHN1\",\n \"direction\": \"outbound\",\n \"type\": \"text\",\n \"body\": \"Your order is on the way!\",\n \"status\": \"queued\",\n \"created_at\": \"2026-05-06T10:21:00+00:00\"\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\": \"Channel not found.\"}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\": \"The channel id field is required when conversation id is not present.\", \"errors\": {\"channel_id\": [\"...\"]}}", "name": "" } ] } ] }, { "name": "OAuth", "description": "\nExchanges a one-time authorization code from the Connect screen\n(\/connect \u2192 user authorizes) for a Sanctum personal access token the\nexternal app can then use as Authorization: Bearer ...\n\nThe flow is intentionally simpler than full OAuth2: no client_secret,\nno PKCE. Security relies on:\n - Codes are one-time (used_at flag).\n - Codes expire in 5 minutes.\n - Codes are bound to a redirect_uri at issue time and the host must\n send the same redirect_uri at exchange time, so an attacker who\n intercepts the redirect URL still can't redeem the code without\n also impersonating the registered redirect target.", "item": [ { "name": "Exchange code for token", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/oauth\/token", "query": [], "raw": "{{baseUrl}}\/api\/v1\/oauth\/token" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"code\":\"4f9e2c...\",\"redirect_uri\":\"https:\\\/\\\/crm.example.com\\\/oktawa\\\/callback\"}" }, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"access_token\": \"1|abc...\",\n \"token_type\": \"Bearer\",\n \"abilities\": [\"read\", \"send\"]\n }\n}", "name": "" }, { "header": [], "code": 400, "body": "{\"error\": \"invalid_grant\", \"message\": \"Authorization code is invalid, used, or expired.\"}", "name": "" } ] } ] }, { "name": "Templates", "description": "", "item": [ { "name": "List templates", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates", "query": [ { "key": "status", "value": "APPROVED", "description": "Filter by Meta status (DRAFT, PENDING, APPROVED, REJECTED, PAUSED, DISABLED).", "disabled": false }, { "key": "language", "value": "ar", "description": "Filter by language code.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/templates?status=APPROVED&language=ar" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-content-type-options", "value": "nosniff" }, { "key": "x-frame-options", "value": "SAMEORIGIN" }, { "key": "referrer-policy", "value": "strict-origin-when-cross-origin" }, { "key": "permissions-policy", "value": "geolocation=(), microphone=(), camera=()" }, { "key": "strict-transport-security", "value": "max-age=63072000; includeSubDomains; preload" }, { "key": "access-control-allow-origin", "value": "*" } ], "code": 401, "body": "{\"message\":\"Unauthenticated.\"}", "name": "" } ] }, { "name": "Send a template message", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates\/send", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates\/send" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"channel_id\":\"01HZK7P5R3Q6V0YH4XJ3M8CHN1\",\"wa_id\":\"966500000000\",\"template_name\":\"order_ready\",\"language\":\"ar\",\"variables\":[\"12345\",\"120 SAR\"]}" }, "description": "Send a Meta-approved template to a wa_id with optional positional\nvariables (1-indexed in Meta, 0-indexed in the array \u2014 variable {{1}}\n= $variables[0])." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": \"01HZK7P5R3Q6V0YH4XJ3M8MSG2\",\n \"type\": \"template\",\n \"status\": \"queued\"\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\": \"Template not found.\"}", "name": "" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }