API and webhooks

Wassla exposes a tenant-scoped HTTPS API for reading conversations, posting messages, and managing knowledge, plus a webhook system that pushes events to your servers as they happen. Authentication uses bearer tokens minted from Settings, and every endpoint is scoped to a single workspace so you cannot accidentally read another tenant's data.

What the public API covers

The API lives behind your workspace and exposes the surface you also see in the Wassla portal. At a high level, you can:

  • List and read conversations across every connected channel — WhatsApp, Instagram, Facebook Page, Twilio SMS, Twilio voice, and the web widget.
  • Send outbound messages, including tenant-initiated WhatsApp templates inside the 24-hour window enforced by Meta.
  • Create and update tickets, assign conversations, and post internal notes.
  • Manage the knowledge base — create, update, and re-embed entries that the AI agent uses for retrieval.
  • Read usage and billing signals such as credits spent, conversations handled, and per-metric breakdowns.

For a guided walkthrough of the developer experience, visit the Documentation hub — it links into Getting Started, Channels, Agents, Knowledge, API Reference, and Security sections. The full endpoint catalogue with request and response shapes is published alongside that hub. If a method is not listed there, treat it as private and subject to change.

How authentication works

Wassla uses bearer tokens. Create one from the portal under Settings, then Developers, then API keys. Click Create key, give it a human-readable name (for example "shipping bot"), pick the scopes you need, and confirm. The full secret is shown exactly once — copy it into your secrets manager immediately, because the portal stores only a one-way hash plus a short prefix for identification.

Scopes

Every key carries one or more of three scopes:

  • read — list and read conversations, messages, knowledge entries, and analytics.
  • write — create messages, update tickets, edit knowledge entries, and trigger compositions.
  • admin — manage channels, team membership, and workspace settings. Grant this sparingly.

Pick the narrowest scope that does the job. A reporting integration almost always needs read only.

Sending requests

Add the key to the Authorization header on every request:

Authorization: Bearer wsk_live_abc123...

Requests without a valid token return 401 unauthorized. Requests with a valid token whose scopes do not cover the action return 403 forbidden. Both responses include a short stable error code that you can branch on in code rather than parsing prose.

Rate limits

Each key has a per-minute rate limit shown next to the key in the portal. When you exceed it you get 429 too_many_requests along with a Retry-After header in seconds. The limiter is fixed-window per key, per tenant, per IP — exponential backoff with jitter is the right client strategy.

Revoking and rotating

To rotate, create a new key, deploy it to your services, then revoke the old key from the same Settings page. Revocation is immediate and audited in the audit log so you can see who pulled which key and when.

Webhook events

Webhooks let your backend react to activity in Wassla without polling. Add a webhook URL under Settings, then Developers, then Webhooks. Pick the event you want, paste an HTTPS endpoint, and save. Wassla will POST a JSON body to that URL each time the event fires for your workspace.

Available event types

The four event types you can subscribe to today are:

  • conversation_end — fires when a conversation is closed, either by your team marking it resolved or by the inactivity timer. The payload includes the conversation id, channel, final status, duration, and a link back to the conversation in the portal.
  • new_message — fires for every inbound and outbound message in any subscribed channel. Useful for mirroring conversations into a CRM or data warehouse.
  • tool_call — fires when the AI agent invokes a tool such as create_ticket, update_ticket, or search_knowledge. Use this to wire up custom side effects when the model decides to take an action.
  • sentiment_result — fires after the background sentiment job classifies a conversation. The payload includes the score and label so you can route negative interactions for review.

More event types — including agent.handoff for human takeover and finer-grained billing events — are on the roadmap. Until then, you can derive handoff state by listening for new_message and checking the handler_mode field on the conversation.

Delivery semantics

Deliveries are at-least-once. Wassla retries failed deliveries with exponential backoff for up to 24 hours, then marks the delivery failed and surfaces it in the Webhooks page so you can inspect the response code and replay manually. Your endpoint must:

  • Respond with a 2xx status within 10 seconds. Anything else is treated as a failure.
  • Be idempotent. Use the delivery_id header to de-duplicate retries.
  • Accept POST with Content-Type: application/json.

Verifying authenticity

Every webhook request includes a signature header computed from your workspace's webhook secret. Verify it on your side before trusting the payload — this prevents a third party who guesses your URL from spoofing events. The verification recipe is documented in the Documentation hub under Security.

Inspecting delivery history

Open Settings, then Developers, then Webhooks, then click any webhook to see its delivery log — status, HTTP response code, attempt count, and timestamp for the most recent attempts. If a delivery is stuck failing, fix your endpoint and the next event will retry automatically; older deliveries can be replayed from the same panel.

When to use the API versus webhooks

Reach for the API when you need to pull data on demand — for example, fetching a conversation transcript when an agent asks for it in your CRM, or backfilling a reporting warehouse. Reach for webhooks when you need to react to something happening — for example, paging an on-call engineer the moment a sentiment score drops below a threshold. Most non-trivial integrations use both: webhooks notify you that something happened, and the API lets you fetch additional context if you need it.