Skip to main content

​
Overview

Use Meta’s WhatsApp Cloud API through Kapso. The proxy forwards Graph requests to Meta and handles auth, while also exposing additional read endpoints for stored conversations, messages, contacts, and calls. Responses use the same Graph style (camelCase in the SDK, snake_case on the wire) and support cursor pagination.

​
Authentication

Two options:

​
Option 1: Bearer token

Use the WhatsApp configuration’s access token: 
Authorization: Bearer YOUR_WHATSAPP_ACCESS_TOKEN

​
Option 2: Project API key

Use your Kapso project API key: 
X-API-Key: YOUR_PROJECT_API_KEY
When using X-API-Key authentication, the WhatsApp configuration is determined from the IDs in your request URL:
  • Endpoints with phone_number_id → resolves config by phone number ID
  • Endpoints with business_account_id → resolves config by business account ID
  • Media endpoints with media_id → requires phone_number_id as query parameter
The API key must belong to the same project as the WhatsApp configuration.

​
Base URL

https://app.kapso.ai/api/meta/{graph_version}/{endpoint}
Example: 
https://app.kapso.ai/api/meta/v23.0/123456789/messages

​
Supported endpoints

​
Meta passthrough (same as Graph)

  • /{phone_number_id}/messages send messages
  • /{phone_number_id}/settings manage settings
  • /{phone_number_id}/flows WhatsApp Flows
  • /{phone_number_id}/media upload media
  • /{phone_number_id}/whatsapp_business_profile business profile
  • /{business_account_id}/message_templates manage templates
  • /{media_id} fetch or delete media (requires phone_number_id as a query when using Kapso)

​
Kapso stored-data endpoints

  • GET /{phone_number_id}/messages list stored message history
  • GET /{phone_number_id}/conversations list conversations
  • GET /conversations/{conversation_id} get a single conversation
  • PATCH /conversations/{conversation_id} update status
  • GET /{phone_number_id}/contacts list contacts
  • GET /{phone_number_id}/contacts/{wa_id} get a contact by WA ID
  • PATCH /{phone_number_id}/contacts/{wa_id} update a contact
  • GET /{phone_number_id}/calls list stored calling events
All list endpoints return { data, paging } with Graph-style cursors.

​
Pagination

List endpoints use cursor pagination. Query parameters:
  • limit number of items to return (1 to 100, default 20)
  • after cursor returned by a previous page
  • before cursor returned by a subsequent page
Response shape: 
{
  "data": [ { "id": "..." } ],
  "paging": {
    "cursors": { "before": "...", "after": "..." },
    "next": "https://...",
    "previous": "https://..."
  }
}

​
Filters (examples)

Messages history GET /{phone_number_id}/messages:
  • direction inbound or outbound
  • status message status filter
  • since ISO timestamp
  • until ISO timestamp
  • conversation_id filter by conversation
Conversations GET /{phone_number_id}/conversations:
  • status active or ended
  • last_active_since ISO timestamp
  • last_active_until ISO timestamp
  • phone_number E.164 customer number
Calls GET /{phone_number_id}/calls:
  • direction INBOUND or OUTBOUND
  • status call status
  • call_id filter a single call

​
Kapso field selector

You can opt into Kapso-only fields using the fields parameter:
  • fields=kapso() omit the Kapso block entirely
  • fields=kapso(flow_response,flow_token) include only specific fields
  • fields=kapso(default) include the default set (also accepts kapso(*) or kapso(all))
See the TypeScript SDK page “Kapso Extensions” for the full list of fields and presets.

​
Media note

When using the Kapso proxy, fetching or deleting media by /{media_id} requires a phone_number_id query parameter to route the request to the correct configuration. The SDK adds this automatically.

​
Errors

On failures, the proxy returns Graph-style error envelopes and an appropriate HTTP status code (for example 400 on bad pagination parameters).

​
Meta documentation

For detailed endpoint documentation, see Meta’s WhatsApp Business Platform API: https://developers.facebook.com/docs/whatsapp/cloud-api
⌘I