Guides
Integration Playbook
Recommended path to connect an ERP, CRM, or SaaS product to Washeej — from credentials to reliable outbound messaging and inbound webhooks.
Canonical API
Build on
/v1. Legacy /external-api remains for existing clients; new work should use API v1.
1. Choose your integration shape
| Shape | Auth | Best for |
|---|---|---|
| Server-to-server | client-id + client-secret + IP whitelist |
ERP / backend jobs / webhooks consumers |
| Embedded SaaS (Connect) | OAuth 2.0 + PKCE | Multi-tenant apps that connect customer Washeej accounts |
See Authentication and OAuth Connect.
2. Connect at least one WhatsApp channel
- Cloud API / Coexistence — hosted onboarding via
POST /devices/cloud/onboarding-sessions(templates, interactive messages, Meta billing). - Device / QR —
POST /devicesthen QR or pairing code (session messaging without Meta templates).
List channels with GET /devices. Prefer an explicit whatsapp_account_id on every send when the account has more than one number.
Details: Channel Selection.
3. Decide how you will message customers
| Need | Use | Guide |
|---|---|---|
| Free-form reply inside 24h | POST /messages |
Session Window |
| Business-initiated / outside 24h (Cloud) | POST /templates/send |
Session Window |
| Native PDF / image / video in a template | DOCUMENT/IMAGE/VIDEO + header_media_url |
Template Media Headers |
| URL inside template text | body_variables |
Dynamic Invoice Link |
| OTP / login codes | AUTHENTICATION templates | Authentication OTP |
| Buttons, lists, location, products | Cloud session message fields | Interactive Messages |
| Session file/image/video/audio | multipart or *_url fields |
Session Media |
4. Register webhooks before going live
POST /webhookswith your HTTPS endpoint and events (message.received, delivery statuses, device events).- Store the secret shown once; verify HMAC signatures.
- Use
POST /webhooks/{id}/testand delivery logs for ops.
See Webhooks.
5. Production checklist
- IP whitelist configured (API key auth).
- Explicit
whatsapp_account_idon send calls in multi-number accounts. - Cloud billing eligible (avoid
billing_blocked). - Respect marketing opt-out (
marketing_suppressed) for MARKETING templates. - Handle
429with exponential backoff (120 req/min/account). - Prefer machine-readable docs for agents: /api-v1-documentation.md.