Zitrabot

Backend Documentation

Backend Developer Documentation

Zitrabot runs a Node and Express backend that powers account onboarding, bot creation, public chat sessions, human handoff, billing, and Meta platform integrations. This documentation starts with the contract developers actually use: authentication, core APIs, and webhook behavior.

What This Backend Does

  • Authenticates workspace owners and support agents with JWT-based bearer tokens.
  • Lets authenticated users create bots, attach API integrations, and expose chat handlers to end users.
  • Runs bot conversations across web chat, WhatsApp, and Instagram, with optional human handoff.
  • Tracks subscription limits for messages and bot count through Paystack-backed billing flows.

How To Read The Docs

  • Start with Authentication if you are building a dashboard client or an internal admin integration.
  • Go to API Reference for the most important request and response shapes used by the frontend and widgets.
  • Use Webhooks if you are connecting Meta channels or debugging inbound messaging behavior.
  • Use Architecture for request flow, runtime boundaries, and ownership across backend layers.

Start Here

These are the pages most developers usually need first when integrating with the backend or extending the product.

Setup

Getting Started

Install dependencies, configure env, and boot the server.

HTTP

API Reference

Complete endpoint map from all Express route files.

Security

Authentication

Sessions, passport OAuth, API keys, and agent auth.

Integrations

Webhooks

WhatsApp and Instagram verification and event intake.

Core Conventions

  • Protected user routes expect `Authorization: Bearer <token>` and fall back to `x-api-key` when implemented through the auth middleware.
  • Most success responses return JSON objects with either direct resource fields or a top-level `message`, `success`, or `token` field.
  • Webhook endpoints acknowledge quickly and do most processing asynchronously to avoid provider retries.

Priority Flows

  • Account lifecycle: register -> verify -> login -> onboarding completion.
  • Bot lifecycle: create bot -> assign features -> create chat handler -> connect channels.
  • Conversation lifecycle: public chat request -> AI reply or handoff -> agent acceptance -> completion.