Mobile API Documentation

Base URL: https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api

Authentication

All endpoints (except POST /login) accept either of: - Bearer token — Authorization: Bearer <access_token> from POST /login. The call is attributed to the logged-in agent. - Organization API key — X-API-Key: cg_... (created in Settings → API Keys). The call is org-scoped with no user context; for call recordings, pass agent_identifier to attribute the call to an agent.

---

1. Login

POST /login — No auth required

Request

{
 "email": "agent@company.com",
 "password": "secret123"
}

Response (200)

{
 "access_token": "eyJ...",
 "refresh_token": "abc...",
 "expires_in": 2592000,
 "user": {
 "id": "uuid",
 "first_name": "Ahmed",
 "last_name": "Ali",
 "email": "agent@company.com",
 "organization_id": "uuid",
 "avatar_url": null
 }
}

Errors

Status	Description
401	Invalid credentials
403	Account deactivated/suspended

---

2. List Contacts

GET /contacts — Bearer token required

Headers

Authorization: Bearer <access_token>

Query Parameters

Param	Default	Description
page	1	Page number
limit	50	Items per page (max 200)
search		Search by name or phone number

Response (200)

{
 "contacts": [
 {
 "id": "uuid",
 "first_name": "Sara",
 "last_name": "Hassan",
 "phones": ["+201001234567"],
 "emails": ["sara@example.com"],
 "tags": ["VIP"],
 "company_id": "uuid",
 "created_at": "2026-03-10T...",
 "updated_at": "2026-03-15T..."
 }
 ],
 "total": 150,
 "page": 1,
 "limit": 50,
 "total_pages": 3
}

---

3. View Single Contact

GET /contacts/:id — Bearer token required

Headers

Authorization: Bearer <access_token>

Response (200)

{
 "id": "uuid",
 "first_name": "Sara",
 "last_name": "Hassan",
 "phones": ["+201001234567"],
 "emails": ["sara@example.com"],
 "tags": ["VIP"],
 "description": "Key account",
 "company_id": "uuid",
 "assignee_id": "uuid",
 "source": "whatsapp",
 "opt_in_status": true,
 "custom_fields": {},
 "created_at": "2026-03-10T...",
 "updated_at": "2026-03-15T...",
 "company": { "id": "uuid", "name": "Acme Corp" }
}

---

4. Upload Call Recording

POST /call-recording — Bearer token or X-API-Key required, multipart/form-data or application/json

Two ways to provide the recording: - Upload the file (multipart/form-data with file) — the API uploads it to the remote Appgain CDN. - Pass a link (recording_url) — if the recording is already hosted on the remote CDN, send its file link (in either the multipart form or a JSON body) and no re-upload happens; the link is saved directly on the call record.

One of file / recording_url is required.

Headers

Authorization: Bearer <access_token> (or X-API-Key: cg_...)
Content-Type: multipart/form-data (or application/json when using recording_url only)

Fields

Field	Required	Description
file	✅*	Audio file (MP3, M4A, WAV, OGG, WebM, AAC, 3GP, AMR). Max 50 MB. Multipart only
recording_url	✅*	Public https link to the recording already on the remote CDN — skips re-upload
contact_id		UUID of the contact (if known)
customer_phone		Phone number — used to auto-match contact if contact_id is empty
agent_identifier		Agent email or phone — attributes the call to an agent when using X-API-Key (Bearer calls are attributed to the logged-in agent automatically)
duration_seconds		Call duration in seconds
call_timestamp		ISO 8601 timestamp (defaults to now)
direction		inbound (default) or outbound
notes		Free-text notes about the call

* Exactly one of file or recording_url must be provided (if both are sent, file wins and is uploaded).

Response (200)

{
 "success": true,
 "call_record_id": "uuid",
 "status": "received",
 "contact_matched": true,
 "recording_stored": true
}

Storage

Recordings are stored remotely on the Appgain CDN; the CDN file URL is saved on the call record. Recordings pushed through this API are never written to the project's own Supabase Storage. - With file: the API uploads it to the CDN (folder connectgain/<appgain_suit_id>). The organization must have an Appgain suit ID configured, otherwise the request fails with 400. - With recording_url: the recording is already on the remote CDN, so nothing is re-uploaded — the provided link is stored directly. The URL must be a public https link (private hosts / IP literals are rejected).

Transcripts produced by processing are stored on the call record in the database (call_records.transcription).

Processing Pipeline

After upload, the recording is automatically processed: 1. Transcription — Speech-to-text (Arabic/English optimized) 2. AI Analysis — Sentiment, keywords, action items, summary 3. Timeline — Results appear on the contact's activity timeline

Errors

Status	Description
400	Missing file/recording_url, unsupported format, invalid recording_url, or Appgain suit ID not configured
401	Invalid/expired token
403	Account deactivated/suspended
500	Upload or processing failure

---

cURL Examples

Login

curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api/login \
 -H "Content-Type: application/json" \
 -d '{"email":"agent@company.com","password":"secret123"}'

List Contacts

curl https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api/contacts?page=1&limit=20 \
 -H "Authorization: Bearer <access_token>"

Upload Recording

curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api/call-recording \
 -H "Authorization: Bearer <access_token>" \
 -F "file=@recording.mp3" \
 -F "customer_phone=+201001234567" \
 -F "duration_seconds=180" \
 -F "direction=outbound" \
 -F "notes=Follow up on pricing"

Register Recording Already on the Remote CDN (no re-upload)

curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api/call-recording \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "recording_url": "https://cdn.appgain.io/connectgain/<suit_id>/recording.mp3",
 "customer_phone": "+201001234567",
 "duration_seconds": 180,
 "direction": "outbound",
 "notes": "Follow up on pricing"
 }'

Same, Authenticated with an Organization API Key

curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api/call-recording \
 -H "X-API-Key: cg_your_api_key_here" \
 -H "Content-Type: application/json" \
 -d '{
 "recording_url": "https://cdn.appgain.io/connectgain/<suit_id>/recording.mp3",
 "agent_identifier": "agent@company.com",
 "customer_phone": "+201001234567",
 "duration_seconds": 180,
 "direction": "outbound"
 }'

---

ConnectGain — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. Open the app · Docs home