{ "info": { "name": "PaalChat API", "description": "PaalChat product API. Set the token and external_id variables. Docs: https://whatsapp.paaltech.org/docs", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://whatsapp.paaltech.org/api/v1" }, { "key": "token", "value": "YOUR_PRODUCT_TOKEN" }, { "key": "external_id", "value": "presec" }, { "key": "waba_id", "value": "102290129340398" }, { "key": "id", "value": "1" } ], "item": [ { "name": "Product", "item": [ { "name": "Get product", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/me", "host": [ "{{baseUrl}}" ], "path": [ "me" ], "query": [] }, "description": "Returns the calling product and the key used: its environment (`live` for real\nbusinesses, `test` for the sandbox), prefix and abilities. Call it when your app starts\nand fail loudly if an ability you need is missing.\n\nAbility: any" } }, { "name": "Get usage", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/usage?", "host": [ "{{baseUrl}}" ], "path": [ "usage" ], "query": [ { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "business", "value": "", "disabled": true } ] }, "description": "Your PaalChat usage per day and type - `message.sent`, `message.received`,\n`template.sent`, `media.processed`, `callback.delivered`, `api.request` - for all your\nbusinesses or one, in the key's environment. Defaults to the last 30 days; at most a\nyear per call. Meta bills WhatsApp messages separately, directly to each business.\n\nAbility: businesses.read" } } ] }, { "name": "Businesses", "item": [ { "name": "List businesses", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses?", "host": [ "{{baseUrl}}" ], "path": [ "businesses" ], "query": [ { "key": "page", "value": "", "disabled": true } ] }, "description": "Your businesses, newest first, 50 per page. Follow `links.next` until it is null.\n\nAbility: businesses.read" } }, { "name": "Create or update business", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses", "host": [ "{{baseUrl}}" ], "path": [ "businesses" ], "query": [] }, "description": "Creates the business, or updates it when the `external_id` already exists. Call it when\na customer signs up and whenever their name or contact details change. Safe to repeat.\n\nAbility: businesses.write", "body": { "mode": "raw", "raw": "{\n \"external_id\": \"st-augustines\",\n \"name\": \"St. Augustine's College\",\n \"email\": \"info@augustines.edu.gh\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get business", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}" ], "query": [] }, "description": "One of your businesses, with its overall WhatsApp status.\n\nAbility: businesses.read" } } ] }, { "name": "WhatsApp", "item": [ { "name": "List library templates", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/template-library?", "host": [ "{{baseUrl}}" ], "path": [ "template-library" ], "query": [ { "key": "sector", "value": "", "disabled": true } ] }, "description": "Starter templates by sector - school (fee reminder, results, PTA meeting, absence,\nadmission offer) and retail (order confirmed, receipt, delivery update) - with named\nvariables and Meta's required example values. Copy one for a business with\n[Create template from library](/docs/api/create-template-from-library).\n\nAbility: templates.read" } }, { "name": "Create connect link", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/connect", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "connect" ], "query": [] }, "description": "A one-time link to PaalChat's hosted \"Connect WhatsApp\" page (Meta Embedded Signup) for\nthis business. Redirect the business's administrator to `url`. Valid for 72 hours and\nuntil used successfully; a new link cancels older unused ones. Success triggers a\n`whatsapp.connection` callback with `event: connected`. Treat the link as a secret.\n\nAbility: connections.manage", "body": { "mode": "raw", "raw": "{\"return_url\": \"https://presec.skuuls.paaltech.org/settings/whatsapp\"}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get WhatsApp state", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp" ], "query": [] }, "description": "The business's WhatsApp side: overall status, each WhatsApp Business Account with its\nhealth and phone numbers. Never contains a Meta token.\n\nAbility: connections.read" } }, { "name": "List phone numbers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/phones", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "phones" ], "query": [] }, "description": "Phone numbers across all the business's WhatsApp Business Accounts.\n\nAbility: connections.read" } }, { "name": "List templates", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/templates?status=APPROVED", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "templates" ], "query": [ { "key": "status", "value": "APPROVED", "disabled": false }, { "key": "name", "value": "", "disabled": true }, { "key": "language", "value": "", "disabled": true }, { "key": "include_removed", "value": "", "disabled": true }, { "key": "page", "value": "", "disabled": true } ] }, "description": "Message templates of the business's WhatsApp accounts, 100 per page, by name. Components are exactly as Meta returns them. Templates Meta deleted are hidden unless `include_removed=1`.\n\nAbility: templates.read" } }, { "name": "Create template", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/templates", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "templates" ], "query": [] }, "description": "Submits a new template to Meta for review on the business's WhatsApp account and mirrors it\n(usually `PENDING`). Meta's decision arrives as a `template.status` callback. `components`\nare Meta's template components, passed through as they are; `category` is marketing,\nutility or authentication. With several WhatsApp accounts, pass `waba_id`. Meta allows\n100 new templates per account per hour.\n\nAbility: templates.manage", "body": { "mode": "raw", "raw": "{\n \"name\": \"fee_reminder\",\n \"language\": \"en_US\",\n \"category\": \"utility\",\n \"parameter_format\": \"named\",\n \"components\": [\n {\n \"type\": \"BODY\",\n \"text\": \"Dear {{parent}}, the fees for {{student}} are due.\",\n \"example\": {\n \"body_text_named_params\": [\n {\"param_name\": \"parent\", \"example\": \"Ama\"},\n {\"param_name\": \"student\", \"example\": \"Kofi\"}\n ]\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Create template from library", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/templates/from-library", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "templates", "from-library" ], "query": [] }, "description": "Copies a [library template](/docs/api/list-template-library) for the business (its name\nfilled in) and submits it to Meta for review, like Create template. The name defaults\nto the library key.\n\nAbility: templates.manage", "body": { "mode": "raw", "raw": "{\"key\": \"school_fee_reminder\"}", "options": { "raw": { "language": "json" } } } } }, { "name": "List template versions", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/templates/{{name}}/versions?", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "templates", "{{name}}", "versions" ], "query": [ { "key": "language", "value": "", "disabled": true } ] }, "description": "Every version of a template's content, newest first, per language - what it said, its\ncategory, Meta's decision on it and where the change came from (`sync`, `api`,\n`library`, `webhook`). History is never deleted, including for removed templates.\n\nAbility: templates.read" } }, { "name": "Delete template", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/templates/{{name}}?", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "templates", "{{name}}" ], "query": [ { "key": "language", "value": "", "disabled": true }, { "key": "waba_id", "value": "", "disabled": true } ] }, "description": "Deletes the template at Meta - one language with `?language=`, otherwise every language of\nthe name - and removes it from PaalChat's mirror. Messages already sent are not affected.\n\nAbility: templates.manage" } }, { "name": "List account transfers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/transfers", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "transfers" ], "query": [] }, "description": "Requests to move a WhatsApp account into or out of this business (`direction`\nincoming / outgoing). PaalTech operators request them; each business approves or\nrejects through its product. After both approve, the account moves 24 hours later\nwith its numbers, templates and connection; messages stay where they happened.\n\nAbility: connections.manage" } }, { "name": "Approve or reject a transfer", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/transfers/{{id}}/{{decision}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "transfers", "{{id}}", "{{decision}}" ], "query": [] }, "description": "This business's answer. Ask the business's owner first - a transfer moves their\nWhatsApp number. A rejection ends the transfer; once both sides approve it completes\nafter 24 hours (`completes_at`), announced as `whatsapp.connection` `transferred_out` /\n`transferred_in`.\n\nAbility: connections.manage" } }, { "name": "Disconnect WABA", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/whatsapp/wabas/{{waba_id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "whatsapp", "wabas", "{{waba_id}}" ], "query": [] }, "description": "Disconnects one WhatsApp Business Account: PaalChat deletes its Meta token and stops\nsending for it. History is kept and the number stays the customer's at Meta. Triggers\na `whatsapp.connection` callback with `event: disconnected`.\n\nAbility: connections.manage" } } ] }, { "name": "Messages", "item": [ { "name": "Send message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/messages", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "messages" ], "query": [] }, "description": "Queues a text, template or media (image, video, audio, document) message - on WhatsApp, or\nwith `channel` sms or email (text; set up with [Set up SMS or email](/docs/api/enable-channel)).\nSMS and email are always business-initiated, so suppression, consent and quiet hours apply. `202` = a new\nmessage, queued; `200` = this `reference` was already submitted and the original message\nis returned (nothing is sent again). Progress arrives as `message.status` callbacks.\nFree-form text and media need an open 24-hour customer service window; otherwise send an\nAPPROVED template. For media, [upload the file](/docs/api/upload-media) first and pass its\n`media.id` (businesses with media enabled).\n\nAbility: messages.send", "body": { "mode": "raw", "raw": "{\n \"to\": \"+233241234567\",\n \"type\": \"template\",\n \"reference\": \"skuul-msg-8812\",\n \"template\": {\n \"name\": \"fees_reminder\",\n \"language\": \"en_US\",\n \"components\": [\n {\n \"type\": \"body\",\n \"parameters\": [\n {\"type\": \"text\", \"text\": \"Mrs Mensah\"},\n {\"type\": \"text\", \"text\": \"Kofi\"},\n {\"type\": \"text\", \"text\": \"450.00\"},\n {\"type\": \"text\", \"text\": \"30 October\"}\n ]\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get message", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/messages/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "messages", "{{id}}" ], "query": [] }, "description": "A message's current status, timestamps and error. Prefer callbacks; use this when you cannot receive them.\n\nAbility: messages.read" } }, { "name": "Cancel scheduled message", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/messages/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "messages", "{{id}}" ], "query": [] }, "description": "Withdraws a message still waiting for its `send_at` (or for the business's quiet hours\nto end). Its status becomes `cancelled` and a `message.status` callback follows. Once\nit is being sent it cannot be cancelled (`409 not_cancellable`).\n\nAbility: messages.send" } }, { "name": "Get Meta usage", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/meta-usage?", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "meta-usage" ], "query": [ { "key": "month", "value": "", "disabled": true } ] }, "description": "The business's WhatsApp usage as Meta priced it, for a month (default this one): per\nsending number and pricing category, billable and free messages and an **estimated**\ncost from Meta's published rate card (list rates, before volume discounts).\n`reconciliation` shows the month compared with Meta's own analytics once checked; where\nthey differ, Meta's figures win. Meta bills the business's WhatsApp Business Account\ndirectly - these amounts never appear on a PaalChat invoice.\n\nAbility: messages.read" } }, { "name": "Estimate Meta cost", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/meta-usage/estimate", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "meta-usage", "estimate" ], "query": [] }, "description": "Before a bulk send: the estimated Meta cost of one category of message to an audience,\ngiven as recipients per calling code. Markets without a rate are listed in `unpriced`,\nnot guessed. An estimate from list rates - Meta bills the business directly.\n\nAbility: messages.read", "body": { "mode": "raw", "raw": "{\"category\": \"marketing\", \"recipients\": {\"233\": 1200, \"234\": 40}}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Billing", "item": [ { "name": "List plans", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/plans", "host": [ "{{baseUrl}}" ], "path": [ "plans" ], "query": [] }, "description": "PaalChat's plans - monthly price, limits (null = no limit) and features. `placeholder`\nplans are examples until PaalTech publishes its prices. Meta's WhatsApp charges are never\npart of a plan.\n\nAbility: any" } }, { "name": "Get billing", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/billing", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "billing" ], "query": [] }, "description": "Two separate blocks. `paalchat`: the business's plan, subscription, usage against its\nlimits and its PaalChat invoices. `meta_whatsapp`: this month's Meta charges, estimated -\nMeta bills the business's WhatsApp Business Account directly; they never appear on a\nPaalChat invoice. Limits apply only while `billing_enabled`.\n\nAbility: billing.manage" } }, { "name": "Pay invoice", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/billing/invoices/{{id}}/pay", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "billing", "invoices", "{{id}}", "pay" ], "query": [] }, "description": "A Paystack checkout link (card or mobile money) for an open PaalChat invoice. Send the business's billing contact there; the invoice is marked paid when Paystack confirms.\n\nAbility: billing.manage", "body": { "mode": "raw", "raw": "{\"email\": \"bursar@presec.edu.gh\"}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Channels", "item": [ { "name": "Get provider health", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/providers", "host": [ "{{baseUrl}}" ], "path": [ "providers" ], "query": [] }, "description": "Whether each provider works right now - Meta (WhatsApp), Arkesel and Hubtel (SMS), Resend (email):\n`healthy`, `degraded` (more than a fifth of the last 15 minutes' sends failed) or\n`unavailable` (calls paused after failures, or not set up). Notifications skip\nunavailable channels.\n\nAbility: any" } }, { "name": "List channels", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/channels", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "channels" ], "query": [] }, "description": "The business's channels - WhatsApp accounts, SMS and email - with their state and their provider's health.\n\nAbility: connections.read" } }, { "name": "Set up SMS or email", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/channels/{{channel}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "channels", "{{channel}}" ], "query": [] }, "description": "Turns SMS or email on for the business. Call again to change anything.\n\n**SMS** goes through `provider` - `arkesel` (the default) or `hubtel` - under\n`sender_id` (1-11 letters, digits or spaces; a business's own sender ID must first be\napproved by that provider). PaalTech's account sends by default. With Arkesel a\nbusiness may send with its own Arkesel account instead: pass `arkesel.api_key`.\nPaalChat checks the key with Arkesel, stores it encrypted and never returns it\n(`own_key: true`); omit it to keep a saved key, send `null` to remove it. Switching\nto Hubtel removes it.\n\n**Email** goes through Resend from `from` - an address on a domain PaalChat sends for.\n\nAbility: connections.manage", "body": { "mode": "raw", "raw": "{\"sender_id\": \"PRESEC\", \"provider\": \"arkesel\"}", "options": { "raw": { "language": "json" } } } } }, { "name": "Turn off SMS or email", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/channels/{{channel}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "channels", "{{channel}}" ], "query": [] }, "description": "Sends on the channel are refused (`409 channel_not_enabled`) until it is set up again.\n\nAbility: connections.manage" } }, { "name": "Send notification", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/notifications", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "notifications" ], "query": [] }, "description": "One notification, tried on `channels` in order (default whatsapp, sms, email) until one\ntakes it. A channel is passed over when there is no content or address for it, the\nbusiness has not set it up, its provider is unavailable, or the send is refused (opted\nout, suppressed...). If its message later fails, the next channel is tried. A message\nwhose fate is unknown never triggers the next channel - it may already have arrived.\nAddresses come from `to`, or from the contact (`contact_id`). Same `reference`, same\nnotification.\n\nAbility: messages.send", "body": { "mode": "raw", "raw": "{\n \"contact_id\": 41,\n \"reference\": \"closing-2026-10-02\",\n \"whatsapp\": {\"template\": {\"name\": \"school_closing\", \"language\": \"en_US\"}},\n \"sms\": {\"text\": \"Presec: school closes at 1pm today.\"},\n \"email\": {\"subject\": \"School closes early\", \"text\": \"School closes at 1pm today.\"}\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get notification", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/notifications/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "notifications", "{{id}}" ], "query": [] }, "description": "Its status and every attempt - channel, outcome and message.\n\nAbility: messages.read" } } ] }, { "name": "Campaigns", "item": [ { "name": "List segments", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/segments", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "segments" ], "query": [] }, "description": "The business's saved segments, by name.\n\nAbility: contacts.read" } }, { "name": "Create segment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/segments", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "segments" ], "query": [] }, "description": "Saves an audience as conditions over the business's contacts (see the\n[Campaigns guide](/docs/campaigns) for fields and operators). Conditions are checked\nwhen saved; contacts are matched each time the segment is used.\n\nAbility: contacts.write", "body": { "mode": "raw", "raw": "{\n \"name\": \"SHS 2 owing fees\",\n \"conditions\": {\n \"all\": [\n {\"field\": \"custom.class\", \"op\": \"eq\", \"value\": \"SHS 2\"},\n {\"field\": \"custom.fee_balance\", \"op\": \"gt\", \"value\": 0}\n ]\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Preview segment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/segments/preview", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "segments", "preview" ], "query": [] }, "description": "How many contacts match conditions (saved or not), with five of them.\n\nAbility: contacts.read", "body": { "mode": "raw", "raw": "{\"conditions\": {\"all\": [{\"field\": \"tag\", \"op\": \"has\", \"value\": \"boarders\"}]}}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get segment", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/segments/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "segments", "{{id}}" ], "query": [] }, "description": "A segment with how many contacts match it now (`count`).\n\nAbility: contacts.read" } }, { "name": "Update segment", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/segments/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "segments", "{{id}}" ], "query": [] }, "description": "Rename it or replace its conditions.\n\nAbility: contacts.write", "body": { "mode": "raw", "raw": "{\"name\": \"SHS 2 and SHS 3 owing\"}", "options": { "raw": { "language": "json" } } } } }, { "name": "Delete segment", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/segments/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "segments", "{{id}}" ], "query": [] }, "description": "Deletes the saved segment; campaigns that used it keep their recipients.\n\nAbility: contacts.write" } }, { "name": "List segment contacts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/segments/{{id}}/contacts?", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "segments", "{{id}}", "contacts" ], "query": [ { "key": "page", "value": "", "disabled": true } ] }, "description": "The contacts matching the segment now, 100 per page.\n\nAbility: contacts.read" } }, { "name": "List campaigns", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/campaigns?", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "campaigns" ], "query": [ { "key": "page", "value": "", "disabled": true } ] }, "description": "The business's campaigns and their runs, newest first, 50 per page.\n\nAbility: campaigns.read" } }, { "name": "Create campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/campaigns", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "campaigns" ], "query": [] }, "description": "A draft broadcast of one APPROVED template to a segment or a list of contacts.\n`parameters` maps each template variable to a source per contact - `field:name`\n(name, phone, email, external_id), `custom:` or `text:`. Preview it,\nthen launch it - now, at `send_at`, or repeating every `week` or `month`.\n\nAbility: campaigns.manage", "body": { "mode": "raw", "raw": "{\n \"name\": \"October fee reminders\",\n \"template\": {\"name\": \"school_fee_reminder\", \"language\": \"en_US\"},\n \"parameters\": {\n \"parent\": \"field:name\",\n \"amount\": \"custom:fee_balance\",\n \"student\": \"custom:ward_name\",\n \"due_date\": \"text:30 October\"\n },\n \"segment_id\": 4,\n \"topic\": \"fees\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get campaign", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/campaigns/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "campaigns", "{{id}}" ], "query": [] }, "description": "A campaign with its results (`stats`). Definitions: `audience` - recipients fixed when\nthe run started; `queued` / `skipped` (with `skip_reasons`) / `cancelled` - what\nPaalChat did with each; `sent`, `delivered`, `read`, `failed` - the messages' statuses\nnow (delivered includes read); `replied` - recipients who wrote back on the same\nconversation within 72 hours of the send; rates are of sent messages, failure of\nsent plus failed; `estimated_meta_cost` - from Meta's pricing reports, an estimate.\n\nAbility: campaigns.read" } }, { "name": "Preview campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/campaigns/{{id}}/preview", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "campaigns", "{{id}}", "preview" ], "query": [] }, "description": "Before launching: how many contacts it will reach, how many will be skipped and why\n(`no_whatsapp`, `missing_parameter`, `recipient_suppressed`, `recipient_opted_out`,\n`recipient_preference_off`), the estimated Meta cost - \"Meta bills your WhatsApp Business\nAccount directly. PaalChat cost: included in your plan.\" - and the number's Meta\nmessaging tier.\n\nAbility: campaigns.read" } }, { "name": "Launch campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/campaigns/{{id}}/launch", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "campaigns", "{{id}}", "launch" ], "query": [] }, "description": "Starts a draft: now (`sending`), or `scheduled` for `send_at` / its repeat. Each person\ngoes through the usual checks - suppression, consent, preferences, limits, quiet hours -\nat the campaign's pace. Repeating campaigns start a run each time (a campaign with\n`parent_id`), with the audience as it is then.\n\nAbility: campaigns.manage" } }, { "name": "Pause, resume or cancel campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/campaigns/{{id}}/{{action}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "campaigns", "{{id}}", "{{action}}" ], "query": [] }, "description": "`pause` stops sending after the current batch; `resume` carries on; `cancel` stops it\nfor good - people not reached yet are marked cancelled and messages still held for quiet\nhours are withdrawn. Cancelling a repeating campaign stops its future runs.\n\nAbility: campaigns.manage" } } ] }, { "name": "Automations", "item": [ { "name": "List automations", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/automations", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "automations" ], "query": [] }, "description": "The business's automations, by name, with how many runs are waiting.\n\nAbility: automations.read" } }, { "name": "Create automation", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/automations", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "automations" ], "query": [] }, "description": "When `trigger` happens to a contact and the optional `conditions` (a segment condition\ntree) hold, run `steps` in order. See the [Automations guide](/docs/automations) for\ntriggers and steps. The definition is checked when saved (templates must be APPROVED).\n\nAbility: automations.manage", "body": { "mode": "raw", "raw": "{\n \"name\": \"Chase unpaid fees\",\n \"trigger\": \"date_reached\",\n \"trigger_config\": {\"field\": \"fee_due_date\", \"offset_days\": -3},\n \"conditions\": {\"all\": [{\"field\": \"custom.fee_balance\", \"op\": \"gt\", \"value\": 0}]},\n \"steps\": [\n {\n \"action\": \"send_template\",\n \"template\": \"school_fee_reminder\",\n \"language\": \"en_US\",\n \"parameters\": {\n \"parent\": \"field:name\",\n \"amount\": \"custom:fee_balance\",\n \"student\": \"custom:ward_name\",\n \"due_date\": \"custom:fee_due_date\"\n }\n },\n {\"action\": \"wait\", \"days\": 3},\n {\n \"action\": \"send_template\",\n \"template\": \"school_fee_reminder\",\n \"language\": \"en_US\",\n \"parameters\": {\n \"parent\": \"field:name\",\n \"amount\": \"custom:fee_balance\",\n \"student\": \"custom:ward_name\",\n \"due_date\": \"custom:fee_due_date\"\n }\n },\n {\"action\": \"notify\", \"data\": {\"reason\": \"fees_overdue\"}}\n ]\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get automation", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/automations/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "automations", "{{id}}" ], "query": [] }, "description": "An automation and its run counts.\n\nAbility: automations.read" } }, { "name": "Update automation", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/automations/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "automations", "{{id}}" ], "query": [] }, "description": "Change any part, or `status` (active or paused). Pausing stops its waiting runs.\n\nAbility: automations.manage", "body": { "mode": "raw", "raw": "{\"status\": \"paused\"}", "options": { "raw": { "language": "json" } } } } }, { "name": "Delete automation", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/automations/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "automations", "{{id}}" ], "query": [] }, "description": "Deletes it with its runs.\n\nAbility: automations.manage" } }, { "name": "List automation runs", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/automations/{{id}}/runs?", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "automations", "{{id}}", "runs" ], "query": [ { "key": "page", "value": "", "disabled": true } ] }, "description": "Its runs, newest first, 50 per page - per contact, with what each step did.\n\nAbility: automations.read" } } ] }, { "name": "Compliance", "item": [ { "name": "Erase contact", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contacts/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contacts", "{{id}}" ], "query": [] }, "description": "The right to be forgotten: removes the contact's name, number, email, your\n`external_id`, custom fields, preferences, tags and identities, the content of their\nmessages, their media files and the notes on their conversations. What remains -\nmessage statuses, conversations, the consent history - points at a pseudonym. Cannot\nbe undone. Their number stays on the suppression list if it is there.\n\nAbility: data.manage" } }, { "name": "Get consent and preferences", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contacts/{{id}}/consents", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contacts", "{{id}}", "consents" ], "query": [] }, "description": "The contact's consent per category (granted, revoked = opted out, or null) and their notification preferences.\n\nAbility: contacts.read" } }, { "name": "Record consent", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contacts/{{id}}/consents/{{category}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contacts", "{{id}}", "consents", "{{category}}" ], "query": [] }, "description": "Record an opt-in you collected (`granted`) or an opt-out (`revoked`). Business-initiated\ntemplates in a revoked category are refused with `recipient_opted_out`. Every change is\nkept in the contact's consent history and announced as `contact.consent`. Contacts also\nopt out of marketing and notifications by replying STOP, and back in with START.\n\nAbility: contacts.write", "body": { "mode": "raw", "raw": "{\"status\": \"granted\", \"source\": \"signup_form\"}", "options": { "raw": { "language": "json" } } } } }, { "name": "Set notification preferences", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contacts/{{id}}/preferences", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contacts", "{{id}}", "preferences" ], "query": [] }, "description": "What the contact wants: channels (`whatsapp`) and topics (`fees`, `results`,\n`attendance`, `pta`, `marketing`, `system`) on or off. Only the keys you send change.\nA template with a `topic` the contact turned off - or any template when WhatsApp is off -\nis refused with `recipient_preference_off`.\n\nAbility: contacts.write", "body": { "mode": "raw", "raw": "{\"topics\": {\"marketing\": false}}", "options": { "raw": { "language": "json" } } } } }, { "name": "List suppressed numbers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/suppressions", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "suppressions" ], "query": [] }, "description": "Numbers the business must not message first (newest first, up to 1,000).\n\nAbility: contacts.read" } }, { "name": "Suppress a number", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/suppressions", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "suppressions" ], "query": [] }, "description": "Business-initiated templates to this number are refused with `recipient_suppressed`\nuntil it is removed. Replies inside the 24-hour window are still possible.\n\nAbility: contacts.write", "body": { "mode": "raw", "raw": "{\"address\": \"+233241234567\", \"reason\": \"Parent asked not to be contacted\"}", "options": { "raw": { "language": "json" } } } } }, { "name": "Remove a suppressed number", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/suppressions/{{address}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "suppressions", "{{address}}" ], "query": [] }, "description": "The business may message the number first again.\n\nAbility: contacts.write" } }, { "name": "Export business data", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/exports", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "exports" ], "query": [] }, "description": "Starts an export of everything PaalChat holds for the business - contacts (with consent\nand preferences), conversations with notes, messages with content, media details - as a\nZIP of JSON Lines files. Poll [Get export](/docs/api/get-export) until `status` is\n`ready`, then download `url` (15 minutes; the file is kept for 24 hours).\n\nAbility: data.manage" } }, { "name": "Get export", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/exports/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "exports", "{{id}}" ], "query": [] }, "description": "An export's status and, once ready, a fresh 15-minute download link.\n\nAbility: data.manage" } } ] }, { "name": "Sandbox", "item": [ { "name": "Simulate an incoming message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/sandbox/incoming", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "sandbox", "incoming" ], "query": [] }, "description": "Test keys only. A customer writes to a connected sandbox business: the message goes\nthrough the live path - contact, conversation, inbox, `message.received` callback - and\nopens the 24-hour window for `from`.\n\nAbility: messages.send", "body": { "mode": "raw", "raw": "{\n \"from\": \"233241234567\",\n \"text\": \"Is there school on Friday?\",\n \"profile_name\": \"Ama Mensah\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Simulate a delivery status", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/sandbox/messages/{{id}}/status", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "sandbox", "messages", "{{id}}", "status" ], "query": [] }, "description": "Test keys only. Meta reports `delivered`, `read` or `failed` for a message you sent in\nthe sandbox: it goes through the live path and fires `message.status`. Statuses only move\nforward, as live.\n\nAbility: messages.send", "body": { "mode": "raw", "raw": "{\"status\": \"delivered\"}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Inbox", "item": [ { "name": "Sign staff in to the inbox", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/inbox/sign-in", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "inbox", "sign-in" ], "query": [] }, "description": "Single sign-on into the PaalChat inbox for a staff member already signed in to your\nproduct. Send who they are and their role (`admin`, `agent` or `viewer`) - PaalChat\nrecords or updates the member - then redirect their browser to `url`. The link works\nonce, within 5 minutes; ask for a new one each time. Pass `conversation_id` to open that\nconversation. PaalChat never holds staff passwords. Needs the inbox enabled for the business.\n\nAbility: inbox.manage", "body": { "mode": "raw", "raw": "{\n \"staff\": {\n \"external_id\": \"teacher-12\",\n \"name\": \"Kwame Owusu\",\n \"email\": \"owusu@presec.edu.gh\",\n \"role\": \"agent\"\n },\n \"conversation_id\": 7\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "List inbox members", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/inbox/members", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "inbox", "members" ], "query": [] }, "description": "The business's staff who have signed in to the inbox, by name - with their role, whether they still have access, and when they were last seen.\n\nAbility: inbox.manage" } }, { "name": "Remove inbox access", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/inbox/members/{{member_id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "inbox", "members", "{{member_id}}" ], "query": [] }, "description": "A staff member left: their inbox access ends at once (an open inbox signs out on its next\nclick) and their conversations become unassigned. Signing them in again restores access.\n\nAbility: inbox.manage" } } ] }, { "name": "Media", "item": [ { "name": "Upload media", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/media", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "media" ], "query": [] }, "description": "Uploads a file to send, as `multipart/form-data` with a `file` field (and an optional\n`filename`, shown for documents). The type is detected from the file itself: JPEG/PNG\nimages (5 MB), MP4/3GP videos (16 MB), AAC/AMR/MP3/M4A/OGG audio (16 MB), and PDF, Word,\nExcel, PowerPoint or text documents (100 MB). Then send a message of that type with\n`media.id`. A file can be sent many times. Needs media enabled for the business. Example:\n`curl -F file=@receipt.pdf -H \"Authorization: Bearer $TOKEN\" .../businesses/presec/media`.\n\nAbility: messages.send" } }, { "name": "Get media", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/media/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "media", "{{id}}" ], "query": [] }, "description": "A media file's details and a fresh signed `url` to its bytes (while `status` is\n`stored`). The link needs no token and expires after 15 minutes - fetch the media again\nfor a new one; never store or share the link. Incoming attachments are `pending` until\nPaalChat has downloaded them from Meta (`media.updated` says when).\n\nAbility: messages.read" } } ] }, { "name": "Contacts", "item": [ { "name": "List contacts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contacts?", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contacts" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "phone", "value": "", "disabled": true }, { "key": "external_id", "value": "", "disabled": true }, { "key": "tag", "value": "", "disabled": true }, { "key": "search", "value": "", "disabled": true } ] }, "description": "The business's contacts, newest first, 50 per page. Contacts are created automatically\nwhen someone messages the business or is messaged; you can also create them yourself.\n\nAbility: contacts.read" } }, { "name": "Create or update contact", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contacts", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contacts" ], "query": [] }, "description": "Finds the contact by your `external_id`, else by `phone`, and updates it - or creates it.\n`custom_fields` must be fields defined for the business (see Define a contact field);\n`tags` replaces the contact's tags. Safe to repeat.\n\nAbility: contacts.write", "body": { "mode": "raw", "raw": "{\n \"external_id\": \"parent-77\",\n \"phone\": \"+233241234567\",\n \"name\": \"Ama Mensah\",\n \"custom_fields\": {\"class\": \"SHS 2\"},\n \"tags\": [\"parent\"]\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get contact", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contacts/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contacts", "{{id}}" ], "query": [] }, "description": "One contact with its identities (how it is reached), custom fields and tags.\n\nAbility: contacts.read" } }, { "name": "Update contact", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contacts/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contacts", "{{id}}" ], "query": [] }, "description": "Change a contact's details, custom fields (`null` clears one) or tags (replaced).\n\nAbility: contacts.write", "body": { "mode": "raw", "raw": "{\"name\": \"Ama Mensah-Boateng\", \"custom_fields\": {\"fee_balance\": 0}}", "options": { "raw": { "language": "json" } } } } }, { "name": "List contact fields", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contact-fields", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contact-fields" ], "query": [] }, "description": "The business's custom contact fields.\n\nAbility: contacts.read" } }, { "name": "Define a contact field", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/contact-fields/{{key}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "contact-fields", "{{key}}" ], "query": [] }, "description": "Create a custom contact field for the business, or change its label, type or choices.\n\nAbility: contacts.write", "body": { "mode": "raw", "raw": "{\"label\": \"Class\", \"type\": \"choice\", \"choices\": [\"SHS 1\", \"SHS 2\", \"SHS 3\"]}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Conversations", "item": [ { "name": "List conversations", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/conversations?status=APPROVED", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "conversations" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "status", "value": "APPROVED", "disabled": false }, { "key": "contact_id", "value": "", "disabled": true }, { "key": "unread", "value": "", "disabled": true } ] }, "description": "The business's conversations, most recent activity first, 50 per page. A conversation is\nbetween one business number and one contact; messages join it as they come and go.\n\nAbility: conversations.read" } }, { "name": "Get conversation", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/conversations/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "conversations", "{{id}}" ], "query": [] }, "description": "One conversation with its contact, status, unread count and whether the 24-hour window is open.\n\nAbility: conversations.read" } }, { "name": "Update conversation", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/conversations/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "conversations", "{{id}}" ], "query": [] }, "description": "Work the conversation: change its `status` (snoozing needs `snoozed_until`), `priority`\nor `tags` (replaced), assign it to an inbox member (`assignee`: the staff member's\n`external_id`, or null to unassign), and send `read: true` when your staff have seen its\nmessages. Changes are announced as `conversation.updated`.\n\nAbility: conversations.manage", "body": { "mode": "raw", "raw": "{\"status\": \"resolved\", \"tags\": [\"fees\"], \"read\": true}", "options": { "raw": { "language": "json" } } } } }, { "name": "List conversation messages", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/conversations/{{id}}/messages?", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "conversations", "{{id}}", "messages" ], "query": [ { "key": "page", "value": "", "disabled": true } ] }, "description": "The conversation's messages, newest first, 50 per page, each with its `content`.\n\nAbility: messages.read" } }, { "name": "List notes", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/conversations/{{id}}/notes", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "conversations", "{{id}}", "notes" ], "query": [] }, "description": "The conversation's internal notes, newest first. Notes are never sent to the contact.\n\nAbility: conversations.read" } }, { "name": "Add note", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/businesses/{{external_id}}/conversations/{{id}}/notes", "host": [ "{{baseUrl}}" ], "path": [ "businesses", "{{external_id}}", "conversations", "{{id}}", "notes" ], "query": [] }, "description": "An internal note for the business's staff. Never sent to the contact; encrypted at rest.\n\nAbility: conversations.manage", "body": { "mode": "raw", "raw": "{\"body\": \"Parent promised to pay on Friday\", \"author\": \"Mrs Owusu (bursar)\"}", "options": { "raw": { "language": "json" } } } } } ] } ] }