jghankins/pewpros-conversations-api.md

PewPros Unified Conversations API

Overview

PewPros now includes a unified Conversations API that supports SMS, voice calls, email, and web chat through a single interface. The system can operate standalone or sync bidirectionally with GoHighLevel (GHL) for customers using their Twilio integration.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   PewPros Mobile App                        │
│                   (pewpros-swift)                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              PewPros Conversations API                       │
│         /api/v1/conversations/* endpoints                    │
│  ─────────────────────────────────────────────────────────  │
│         Pewpros.Conversations context                        │
│              (source of truth)                               │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  Standalone     │ │   GHL Mode      │ │  Direct Twilio  │
│  (No Provider)  │ │  sms_provider   │ │  sms_provider   │
│                 │ │    = "ghl"      │ │   = "twilio"    │
│  - Local DB     │ │                 │ │                 │
│  - No SMS/Voice │ │  - Sync to GHL  │ │  - Direct API   │
│  - Web chat OK  │ │  - Webhooks in  │ │  - Webhooks in  │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Supported Channels

Channel	Description	Provider Required
`sms`	Text messages	GHL or Twilio
`voice`	Phone calls	GHL or Twilio
`email`	Email threads	Future
`web`	Website chat widget	None (built-in)
`whatsapp`	WhatsApp messages	GHL

Provider Configuration

Option 1: GHL Mode (Default)

Uses GoHighLevel's Twilio integration. Recommended for customers already using GHL.

Tenant Settings:

sms_provider: "ghl"
ghl_api_key_encrypted: "pit_xxxxx"
ghl_location_id: "loc_xxxxx"

Option 2: Direct Twilio Mode

Bypasses GHL, talks directly to Twilio API. For customers not using GHL.

Tenant Settings:

sms_provider: "twilio"
twilio_account_sid_encrypted: "ACxxxxx"
twilio_auth_token_encrypted: "xxxxx"
twilio_phone_number: "+15551234567"
twilio_messaging_service_sid: "MGxxxxx"  # Optional, for A2P 10DLC

Option 3: Disabled

SMS/Voice disabled, only web chat works.

sms_provider: nil

API Endpoints

All endpoints require authentication via Bearer token.

Conversations

Method	Endpoint	Description
`GET`	`/api/v1/conversations`	List conversations
`POST`	`/api/v1/conversations`	Create conversation
`GET`	`/api/v1/conversations/:id`	Get conversation + messages
`PUT`	`/api/v1/conversations/:id`	Update conversation
`POST`	`/api/v1/conversations/:id/assign`	Assign to current user
`POST`	`/api/v1/conversations/:id/close`	Close conversation
`POST`	`/api/v1/conversations/:id/reopen`	Reopen conversation

Messages

Method	Endpoint	Description
`GET`	`/api/v1/conversations/:id/messages`	List messages
`POST`	`/api/v1/conversations/:id/messages`	Send message in conversation
`POST`	`/api/v1/conversations/:id/read`	Mark messages as read
`POST`	`/api/v1/conversations/send`	Send to contact/phone (creates conversation)

Unread

Method	Endpoint	Description
`GET`	`/api/v1/conversations/unread`	Get unread count

Query Parameters

List Conversations

GET /api/v1/conversations?channel=sms&status=open&search=john&limit=50&offset=0

Param	Description
`channel`	Filter by channel: `sms`, `voice`, `email`, `web`
`status`	Filter by status: `open`, `closed`, `archived`
`contact_id`	Filter by contact ID
`assigned_to`	Filter by assigned user ID
`search`	Search by name, phone, or email
`limit`	Pagination limit (default 50)
`offset`	Pagination offset

Request/Response Examples

Send SMS to Contact

POST /api/v1/conversations/send
Content-Type: application/json
Authorization: Bearer <token>

{
  "contact_id": 123,
  "message": "Hello! This is a test message.",
  "channel": "sms"
}

Response:

{
  "data": {
    "conversation": {
      "id": 456,
      "channel": "sms",
      "status": "open",
      "phone_number": "+15551234567",
      "contact": {
        "id": 123,
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+15551234567"
      }
    },
    "message": {
      "id": 789,
      "body": "Hello! This is a test message.",
      "direction": "outbound",
      "delivery_status": "sent",
      "inserted_at": "2026-03-05T20:00:00Z"
    },
    "status": "sent"
  }
}

Send SMS to Phone Number

POST /api/v1/conversations/send
{
  "phone": "+15559876543",
  "message": "Hello from PewPros!",
  "channel": "sms"
}

Reply in Conversation

POST /api/v1/conversations/456/messages
{
  "message": "Thanks for your reply!"
}

Webhooks

GHL Mode

Configure GHL to send webhooks to:

POST https://your-domain.com/webhooks/ghl

Supported events:

IncomingSMS / sms.inbound
IncomingCall / call.inbound
CallCompleted / call.completed
SMSDelivered / sms.delivered
SMSFailed / sms.failed

Direct Twilio Mode

Configure Twilio webhooks to:

POST https://your-domain.com/webhooks/twilio

(Webhook controller for direct Twilio to be implemented)

Database Schema

conversations table

- id: bigint (PK)
- channel: string ("sms", "voice", "email", "web", "whatsapp")
- status: string ("open", "closed", "archived")
- phone_number: string
- visitor_name: string
- visitor_email: string
- visitor_phone: string
- visitor_token: string (for web chat)
- ghl_conversation_id: string (GHL sync)
- contact_id: FK -> contacts
- assigned_to: FK -> users
- last_message_at: datetime
- metadata: jsonb
- inserted_at, updated_at

chat_messages table

- id: bigint (PK)
- conversation_id: FK -> conversations
- sender_id: FK -> users (nullable)
- sender_type: string ("visitor", "staff", "system")
- body: text
- channel: string
- direction: string ("inbound", "outbound")
- delivery_status: string ("pending", "sent", "delivered", "read", "failed")
- ghl_message_id: string
- call_duration_seconds: integer (for voice)
- recording_url: string (for voice)
- read_at: datetime
- inserted_at, updated_at

iOS App Integration

The pewpros-swift app includes:

ConversationsViewModel - Full CRUD for conversations
UnifiedConversation / UnifiedMessage models
Views for listing, viewing, and composing messages
Support for all channels with appropriate UI

Endpoints Used

case conversationsUnified           // GET /conversations
case conversationsUnifiedUnread     // GET /conversations/unread
case conversationUnified(id: Int)   // GET /conversations/:id
case conversationMessages(id: Int)  // GET /conversations/:id/messages
case conversationSendMessage(id: Int) // POST /conversations/:id/messages
case conversationAssign(id: Int)    // POST /conversations/:id/assign
case conversationCloseUnified(id: Int) // POST /conversations/:id/close
case conversationReopen(id: Int)    // POST /conversations/:id/reopen
case conversationMarkRead(id: Int)  // POST /conversations/:id/read
case conversationsSend              // POST /conversations/send

Files Added/Modified

Backend (pewpros)

New Files:

lib/pewpros/conversations.ex - Main context module
lib/pewpros/integrations/twilio.ex - Direct Twilio client
lib/pewpros_web/controllers/api/v1/conversations_controller.ex
lib/pewpros_web/controllers/api/v1/conversations_json.ex
lib/pewpros_web/controllers/webhooks/ghl_webhook_controller.ex
priv/repo/migrations/*_add_sms_channel_to_conversations.exs
priv/repo/migrations/*_add_twilio_fields_to_tenants.exs

Modified Files:

lib/pewpros/chat/conversation.ex - Added channel fields
lib/pewpros/chat/message.ex - Added SMS/voice fields
lib/pewpros/tenants/tenant.ex - Added Twilio fields
lib/pewpros/integrations/ghl.ex - Added Conversations API
lib/pewpros_web/router.ex - Added routes

iOS (pewpros-swift)