Using the API and webhooks

The only technical page in this manual. If you are not writing code, nothing here affects you — everything the API does can be done from the screens.

This page is a signpost. The full reference — endpoints, request and response shapes, authentication, error codes — is at Developers, with a machine- readable OpenAPI spec alongside it. Deliberately not repeated here: two copies of an API reference drift apart, and one of them is then wrong.

You need an account to open the reference

This manual is public, but the API reference, the OpenAPI spec and your keys all live inside the app — you have to be signed in to a Wap2b account to reach them. If you are building this for a client, ask them to invite you to their account as an Admin, or create your own to read the docs and test against.

What the API is for

Connecting your own systems to Wap2b, so messaging happens without anyone opening a browser:

Sync contacts from your CRM, shop or booking system as they are created.
Send messages from your own application — order confirmations at the moment of order, passcodes at the moment of login.
Receive callbacks when a message's delivery status changes, so your system knows what happened without polling.

Getting a key

Open API keys.
Create a key and copy it immediately — it is shown once.
Send it as a header on each request. The exact header name and format is in the reference.

Keys are credentials

Server-side only. A key in front-end JavaScript, a mobile app or a public repository is a key someone else can send messages with, on your balance. Rotate it from API keys if one is ever exposed.

What the API covers

Area	Endpoint
Contacts	`POST /api/v1/contacts` — create and update, in batches
Messages	`POST /api/v1/messages` — send a template to a number
Callbacks	Outbound webhooks — see below

Shapes, limits and examples are in the reference.

The contacts API needs a funded account

Contact writes are free to call, but require a small minimum balance on the account — ₹200 for Indian accounts. It keeps the write endpoints a feature of a real account rather than a free contacts database. The exact figure for your currency is in the reference.

Webhooks

A webhook is Wap2b calling your system when something happens, so you find out without asking repeatedly.

Currently one event is published: message.status — fired when a message's delivery status changes (sent, delivered, read, failed).

Set the destination URL on Integrations. Your endpoint should:

Respond quickly, and do the real work afterwards. A slow endpoint gets treated as a failed delivery.
Tolerate repeats. Assume any event may arrive more than once and make handling it idempotent.
Not assume ordering. A delivered can arrive before the sent that preceded it.

Signature verification and the payload shape are documented in the reference.

Sensible practice

Use the same templates as the screens. A template sent through the API is the same template, with the same approval and the same price.
Handle failures in your own system. A failed status is information you should act on — flag the customer record rather than silently retrying forever.
Watch the source filter. Message logs can be filtered to API sends only, which is the fastest way to see what your integration is actually doing.
Test against one number first. Same advice as for broadcasts, and for the same reason.

If something goes wrong

401 or 403. Bad, revoked or wrongly-sent key. Check the header format in the reference.
A contact write is rejected for balance. The account is below the contacts-API minimum. Top up on Recharges.
Messages send but nothing arrives. Not an API problem — work through I can't send messages.
Webhooks are not arriving. Check the URL is publicly reachable over HTTPS and responds quickly. Delivery attempts and their outcomes are shown on Integrations.