Inbox & Messaging API

The Inbox & Messaging API powers Pingr AI’s customer communication hub. It bridges customer interactions across Meta WhatsApp Cloud API, automated AI voice & text agents, and human support representatives into unified conversation tickets.

+-------------------------------------------------------------+
|             Omnichannel Inbox & Messaging Architecture      |
|                                                             |
|   +-----------------------+     +-----------------------+   |
|   | WhatsApp Cloud Webhook|     | Agent Chat UI / SDK   |   |
|   +-----------+-----------+     +-----------+-----------+   |
|               \                             /               |
|                v                           v                |
|              +-------------------------------+              |
|              |     Pingr AI Inbox Service    |              |
|              |  (Ticket Router & Dispatcher) |              |
|              +---------------+---------------+              |
|                              |                              |
|              +---------------+---------------+              |
|              |                               |              |
|              v                               v              |
|     +-----------------+             +-----------------+     |
|     | PostgreSQL DB   |             | Cloud Storage   |     |
|     | (Threads & Msgs)|             | (Images/Audio/Doc)    |
|     +--------+--------+             +-----------------+     |
|              |                                              |
|              v                                              |
|     +-----------------+                                     |
|     | WebSocket Stream| <----> Live Agent Dashboard Sync    |
|     +-----------------+                                     |
+-------------------------------------------------------------+

Key Capabilities

Ticket Lifecycle Management

Organize contact discussions into structured tickets with open and closed status lifecycles.

Rich Two-Way WhatsApp Messaging

Send and receive text, images, documents, audio clips, and video files with context-aware reply threads (context_message_id).

Secure Media Upload & Streaming

Upload attachments securely to cloud object storage and stream media directly through authenticated endpoints.

Interactive Emoji Reactions

Send and clear WhatsApp emoji reactions (👍, ❤️, 🎉) on individual messages with instant WebSocket broadcast.

Ticket Lifecycle & Statuses

Each conversation thread between an organization and a contact is represented by an Inbox Ticket:

Active Ticket: Contacts have at most one open ticket at a time. New incoming or outgoing messages append directly to this thread.
Closed Ticket: When a conversation issue is resolved, agents or automations patch the ticket status to closed. Subsequent new contact engagements will spawn or reopen a fresh ticket.

Status	Meaning
`open`	Active ticket receiving live messages; visible in unread agent queues.
`closed`	Resolved ticket archived in conversation history.

Supported Message Types

When sending messages via POST /api/v1/inbox/messages/{inbox_id}:

Type	Description	Required Parameters
`text`	Standard plain-text message	`body`
`image`	PNG, JPEG, or WebP picture	`media_url`, optional `body` (caption)
`document`	PDF, DOCX, or spreadsheet file	`media_url`, optional `media_filename`
`audio`	Voice note or recorded audio clip	`media_url`, `media_mime_type`
`video`	MP4 or standard video recording	`media_url`, optional `body` (caption)

Available Endpoints

Tickets & Conversations

Method	Endpoint	Description
POST	`/api/v1/inbox/tickets`	Create a new ticket or return existing open ticket for a contact
GET	`/api/v1/inbox/tickets`	List conversation tickets with status and contact filtering
GET	`/api/v1/inbox/tickets/{inbox_id}`	Retrieve details and contact profile for a specific ticket
PATCH	`/api/v1/inbox/tickets/{inbox_id}`	Update ticket status (`open` or `closed`)

Messaging & Media

Method	Endpoint	Description
GET	`/api/v1/inbox/messages`	List messages across the organization or for a ticket
GET	`/api/v1/inbox/messages/{inbox_id}`	Retrieve chronological message history for a ticket
POST	`/api/v1/inbox/messages/{inbox_id}`	Send WhatsApp text or rich media message
POST	`/api/v1/inbox/upload`	Upload media attachment to S3 storage prior to sending
GET	`/api/v1/inbox/media/{message_id}`	Securely stream and download attached media
POST	`/api/v1/inbox/messages/{message_id}/react`	Add or clear emoji reaction on a WhatsApp message

Overview

Agents

Campaigns

Contacts

Templates

Knowledge Base

Webhooks

Call Logs

Quick Replies

Inbox

Inbox & Messaging Overview

Inbox & Messaging API

Key Capabilities

Ticket Lifecycle Management

Rich Two-Way WhatsApp Messaging

Secure Media Upload & Streaming

Interactive Emoji Reactions

Ticket Lifecycle & Statuses

Supported Message Types

Available Endpoints

Tickets & Conversations

Messaging & Media

​Inbox & Messaging API

​Key Capabilities

Ticket Lifecycle Management

Rich Two-Way WhatsApp Messaging

Secure Media Upload & Streaming

Interactive Emoji Reactions

​Ticket Lifecycle & Statuses

​Supported Message Types

​Available Endpoints

​Tickets & Conversations

​Messaging & Media

Inbox & Messaging API

Key Capabilities

Ticket Lifecycle & Statuses

Supported Message Types

Available Endpoints

Tickets & Conversations

Messaging & Media