Skip to content
PaalChat Docs

Support

Changelog

Changes to the PaalChat API.

.md

2026-10-04

  • Self-serve accounts: trust rules. Accounts that sign up themselves verify their phone by SMS before sending templates (account_not_verified), and new accounts have a daily limit of business-initiated messages that rises with the account's age and record (sending_limit_reached). When Meta flags a number's quality, the business's campaigns pause. Products PaalTech set up are not affected by the limits.
  • AI assistant (dashboard): self-serve businesses can switch on an assistant that answers customers from what they teach it (FAQs, text, documents, web pages) - Suggest drafts replies for staff, Auto replies and hands over to people. Scoped to the business's own purpose, per WhatsApp's rules. No API changes yet; assistant settings through the API come next.

2026-10-03

  • Arkesel SMS: SMS can go through Arkesel (now the default for new SMS setups) or Hubtel, chosen per business with provider on Set up SMS or email. A business may send with its own Arkesel account (arkesel.api_key, checked and stored encrypted; own_key on the connection). New errors invalid_provider_credentials and provider_unavailable; arkesel in provider health.
  • Inbox, Connect and status pages: light and dark themes (following the device by default), a refreshed design, and an inbox that shows delivery ticks on each reply. No API changes.

2026-10-02

  • PaalChat billing (off until prices are published): plans with limits and features, Get billing (PaalChat and Meta shown apart), invoices paid through Paystack. New scope billing.manage; errors plan_limit_reached, plan_feature_missing, payment_unavailable.
  • SMS, email and failover: SMS through Hubtel and email through Resend per business (channel on Send message), notifications that fall back between channels (notification.updated), and provider health (GET /providers). Errors channel_not_enabled, channel_not_allowed.
  • Operations: a public status page (and /status.json), and WhatsApp account transfers between businesses that both sides approve (whatsapp.connection events transfer_requested, transferred_out, transferred_in).
  • Automations: triggers (message received, keyword, contact created, conversation status, date field), conditions, steps with waits, run logs, and the automation.action callback. New scopes automations.read / automations.manage.
  • Segments, scheduling and campaigns: saved segments over contact fields, tags and consent; send_at on template sends with Cancel scheduled message (status cancelled); campaigns with preview (skips, estimated Meta cost), pacing, repeat, pause/resume/cancel and results (campaign.updated). Scopes campaigns.read / campaigns.manage are now in use.
  • Templates as a product: template versions and history (removed templates are kept), parameters checked before sending (invalid_template_parameters), and a template library for schools and shops. Fix: templates created through the API now reach Meta with their full components (text and examples were dropped before).
  • Meta usage estimates: Get Meta usage (per number and category, compared with Meta's own analytics) and Estimate Meta cost for an audience. Estimates only; Meta bills businesses directly.
  • Data rights: per-business retention (retention.message_content_days), Export business data, and Erase contact; new ability data.manage.
  • Consent and quiet hours: STOP/START replies, Record consent, notification preferences, a suppression list, and business quiet hours with time zones - checked before every business-initiated template. New callback contact.consent; new fields category, topic, urgent on Send message and scheduled_for on messages; ability messages.urgent.
  • PHP SDK and Laravel package (paaltech/paalchat-php, paaltech/paalchat-laravel) and a written versioning policy; responses carry X-PaalChat-API-Version, and deprecated endpoints will carry Deprecation and Sunset headers.
  • API keys: sk_live_ and sk_test_ keys, revocable, optionally tied to IP addresses; GET /me shows the key's environment and prefix. Older ptw_ tokens keep working.
  • Sandbox: test keys work on sandbox businesses with simulated WhatsApp - connect in one click, simulate incoming messages and delivery statuses. Callbacks carry sandbox.
  • Idempotency-Key header on every write; per-business rate limit (120/minute) and optional daily message cap; Get usage for PaalChat usage per day.
  • Inbox: a business's staff work their conversations in PaalChat, signed in from your product with a one-time link (Sign staff in to the inbox). Roles admin, agent and viewer; remove access when staff leave. Conversations have an assignee (an inbox member), set through Update conversation. New ability inbox.manage, error unknown_member.
  • Media: incoming attachments are downloaded and stored by PaalChat (media_id on message.received, then a media.updated callback with a 15-minute signed link); upload files and send image, video, audio and document messages. Endpoints Upload media and Get media; errors feature_disabled, unknown_media, media_not_ready, media_type_mismatch, unsupported_media, media_too_large. Enabled per business.

2026-10-01

  • Templates through the API: create (submitted to Meta for review) and delete (one language or all) with the templates.manage scope. New errors template_rejected, waba_required, meta_unavailable.
  • Contacts and conversations API: list, get and upsert contacts (your own external_id, custom fields, tags), define custom fields, list and work conversations (status, priority, tags, read), read their messages with content, add internal notes. New scopes conversations.read / conversations.manage; new events contact.created, contact.updated, conversation.created, conversation.updated. Messages and their callbacks carry contact_id and conversation_id. See Contacts and conversations.
  • PaalChat now keeps each business's contacts and conversations, and the content of messages (encrypted, 365 days by default) - see the FAQ. API access to them is coming.
  • A product can have several webhook endpoints, each with its own secret and an optional filter by event, business or channel - see Callbacks. Your existing callback URL is your default endpoint and receives everything, as before.
  • Every response carries X-Request-ID (send your own to correlate), repeated in error bodies as error.request_id - see Errors.
  • Token scopes renamed to <resource>.<action>: businesses.read, businesses.write, connections.read, connections.manage, templates.read, messages.read, messages.send (plus reserved scopes for coming endpoints). Existing tokens were converted automatically - see Authentication.
  • Messages carry Meta's pricing (billable, category, type, model) in the message resource and message.status. New guide: WhatsApp pricing.
  • New message status unknown: Meta's answer to a send was lost, so it may or may not have been delivered; it is never resent automatically.
  • The 24-hour window is checked per sending number, as Meta applies it.
  • Connect links accept a return_url only on your product's registered origins (422 return_url_not_allowed).
  • "Free text" is now called "free-form text" in the docs.
  • Connection states are now pending, connecting, connected, degraded, maintenance, suspended, revoked and disconnected (error is gone - see Connection states), with matching whatsapp.connection events. New 409 connection_paused.
  • A WhatsApp account's health.credential (a status) is now health.has_credential (true/false); the account's own status says whether it works.

2026-09-30 - v1

  • Businesses: list, get, create or update by external_id.
  • WhatsApp: hosted Embedded Signup connect links, connection state and health, phone numbers, templates, disconnect.
  • Messages: send text and template messages with idempotent references; read a message's status.
  • Callbacks: message.received, message.status, template.status, whatsapp.connection, signed with X-PaalChat-Signature.
  • One error format for every endpoint: {"error": {"code", "message"}}.