Zitrabot

Backend Documentation

Webhooks

Zitrabot uses webhook endpoints primarily for Meta channels. The backend acknowledges incoming webhook requests quickly, then processes messages asynchronously to reduce retries from the provider.

Important Runtime Behavior

  • Both WhatsApp and Instagram POST handlers send `200` immediately before doing heavier work.
  • Incoming messages are deduplicated with the `ProcessedMessage` model to prevent duplicate AI replies across retries.
  • Conversation state is persisted in MongoDB so handoff and channel logic can survive across requests.

What The Backend Does After Ack

  • Locates the target bot from channel metadata such as WhatsApp phone number ID or Instagram business user ID.
  • Builds a system prompt from bot description and training data.
  • May execute commerce or scheduling tools before generating the final reply.
  • Sends the outbound provider message through the Meta Graph API and persists both sides of the exchange.

Verification Endpoints

These endpoints are used once when registering the callback URL with Meta, and any time Meta re-checks ownership.

GET/api/webhook

Verifies ownership of the WhatsApp webhook endpoint.

Meta Verify Token

Request

  • Meta sends `hub.mode`, `hub.verify_token`, and `hub.challenge` as query parameters.
  • The backend compares `hub.verify_token` to `WHATSAPP_VERIFY_TOKEN`.

Response

  • On success, the server returns the raw `hub.challenge` with status `200`.
  • On failure, the server returns `403`.
GET/api/instagram

Verifies ownership of the Instagram webhook endpoint.

Meta Verify Token

Request

  • Meta sends `hub.mode`, `hub.verify_token`, and `hub.challenge` as query parameters.
  • The backend compares `hub.verify_token` to `INSTAGRAM_VERIFY_TOKEN`.

Response

  • On success, the server returns the challenge with status `200`.
  • On failure, the server returns `403`.

Inbound Message Endpoints

These routes ingest real customer traffic. They are intentionally lightweight at the HTTP layer and do the actual business work after acknowledging the webhook.

POST/api/webhook

Receives WhatsApp webhook payloads, deduplicates events, routes them to the correct bot, and either continues with AI or starts human handoff.

Meta

Request

  • The backend expects Meta-style webhook payloads under `entry -> changes -> value`.
  • Text messages trigger normal AI flow; image messages can trigger receipt validation when a pending transaction exists.

Response

  • Returns `200` immediately to Meta.
  • Actual bot replies are sent later through the Graph API, not as the HTTP response body.

Notes

  • Text flow supports tool calling, conversation phase management, and human handoff decisions.
  • Image flow can validate transfer receipts and update transaction state.
POST/api/instagram

Receives Instagram webhook payloads, finds the mapped bot, generates an AI reply, and sends the reply back through Instagram messaging APIs.

Meta

Request

  • The backend expects a `messages` field event and reads sender, recipient, text, and message ID from the webhook body.

Response

  • Returns `200` immediately to Meta.
  • Outbound reply delivery happens asynchronously using the bot's stored Instagram access token.

Common Errors

  • 404 bot not found for recipient business ID
  • logged processing errors after ack