Integration Guide

Build custom applications on Wallin's APIs.

Wallin provides three main APIs for different use cases:

OTP API

Deliver One-Time Password (OTP) codes to customers via WhatsApp for authentication or account verification.

Use cases: Account login, sensitive action verification, password resets

Learn more: 02-otp-api.md

WhatsApp Messaging API

Send and receive WhatsApp messages from your backend, outside the Wallin Inbox.

Use cases: Transactional messages (order updates, alerts), high-volume sends, custom integrations

Learn more: 03-whatsapp-messaging-api.md

Agent API

Build a custom agent frontend or automate conversation management.

Use cases: Custom agent UX, conversation automation, reporting dashboards

Learn more: 04-agent-api.md

Getting Started

1. Understand Authentication

Wallin uses three authentication mechanisms depending on the API:

• Sanctum Token — For Agent API (login with email/password, receive a token)
• OTP API Key — For OTP API (static key in X-Wallin-OTP-Key header)
• Sanctum Token + Tenant — For WhatsApp API (same as Agent API)

Learn more: 01-authentication.md

2. Handle Errors

All APIs return structured error responses with status codes and error codes.

Common patterns:

• 400 Bad Request — validation error (field is missing, wrong format)
• 401 Unauthorized — missing/invalid auth (wrong token, expired session)
• 403 Forbidden — permission denied (trying to access another org's data)
• 429 Too Many Requests — rate limited (try again after Retry-After seconds)
• 500 Internal Server Error — server error (rare; contact support if persistent)

Learn more: 05-errors-and-limits.md

3. Test Locally

Wallin supports a simulation mode for development (WHATSAPP_SIMULATE_API=true). No actual WhatsApp message is sent; responses are mocked.

Learn more: 06-testing-and-sandbox.md

4. See Examples

Complete curl examples for common workflows (OTP verification, sending messages, agent bot).

Learn more: 07-example-flows.md

Base URL

Replace {WALLIN_URL} with your Wallin domain in examples:

• Local dev: http://localhost:8003
• Production: https://app.wallin.example (your domain)

Rate Limits

All endpoints respect Meta platform limits and internal rate limiting.

Exceeding limits returns 429 Too Many Requests with a Retry-After header.

Webhooks

Wallin sends events to registered webhooks when conversations are created, messages arrive, or status changes. Webhook URLs are configured per connection at /channels/{connectionId}.

Events:

• message.received — New inbound message
• message.status_updated — Message delivery/read status changed
• conversation.created — New conversation started
• conversation.assigned — Conversation reassigned

Webhooks are signed with X-Wallin-Signature (HMAC-SHA256 of the request body using your connection's secret).

Multi-tenancy

If your account has multiple organizations, pass X-Organization-Id header to specify which one. If omitted, requests use your user's current organization context.

curl https://wallin.example/api/agent/conversations \
  -H "Authorization: Bearer token" \
  -H "X-Organization-Id: 5"

Support

For API issues, refer to the error details in responses. Common problems are documented in 05-errors-and-limits.md and 08-troubleshooting/01-faq.md.

For deeper integration questions, contact support@wallin.example.