ConnectGain Complete API Documentation¶

Overview¶

ConnectGain provides three types of APIs: 1. Supabase Edge Functions - Custom serverless functions 2. Supabase REST API - Direct database access 3. External APIs - APIs for external systems (using API keys)

Table of Contents¶

Authentication
Edge Functions API
External APIs
REST API - Contacts
REST API - Deals/Leads
REST API - Conversations
REST API - Messages
REST API - Tasks
Error Responses

Base Configuration¶

Base URL: https://txpaxbxhnvnhsjwwaeoy.supabase.co REST API URL: /rest/v1/ Functions URL: /functions/v1/

Authentication¶

Standard Authentication (Bearer Token)¶

Most APIs use Bearer token authentication:

Authorization: Bearer YOUR_ANON_KEY
apikey: YOUR_ANON_KEY

Get your anon key from: Supabase Dashboard → Settings → API

API Key Authentication (External Systems)¶

External APIs use X-API-Key header:

X-API-Key: cg_abc123def456...

API keys are generated per organization and can be created via the Create API Key endpoint.

Edge Functions API¶

Send Messages¶

WhatsApp Lite - Send Message¶

Endpoint: POST /functions/v1/whatsapp-lite-send

Headers:

Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json

Body:

{
 "to": "201001383533",
 "message": "Hello!",
 "suitId": "YOUR_SUIT_ID",
 "organizationId": "org-uuid",
 "contactName": "John Doe",
 "from": "AIBot",
 "conversationId": "conv-uuid"
}

Curl:

curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Hello!",
 "suitId": "YOUR_SUIT_ID",
 "from": "AIBot"
 }'

Response:

{
 "success": true,
 "result": {
 "messageId": "message_id",
 "id": "message_id"
 },
 "conversationId": "conv-uuid",
 "contactId": "contact-uuid"
}

See WHATSAPP_LITE_API_GUIDE.md for complete WhatsApp documentation.

WhatsApp Cloud - Send Message¶

Endpoint: POST /functions/v1/whatsapp-cloud-send

Body:

{
 "to": "phone_number",
 "message": "Hello via Cloud API!",
 "conversationId": "conv-uuid",
 "accessToken": "facebook_access_token",
 "phoneNumberId": "phone_number_id"
}

Messenger - Send Message¶

Endpoint: POST /functions/v1/messenger-send

Body:

{
 "to": "user_psid",
 "message": "Hello via Messenger!",
 "conversationId": "conv-uuid",
 "accessToken": "messenger_access_token"
}

Instagram - Send Message¶

Endpoint: POST /functions/v1/instagram-send

Body:

{
 "to": "instagram_user_id",
 "message": "Hello via Instagram!",
 "conversationId": "conv-uuid"
}

Telegram - Send Message¶

Endpoint: POST /functions/v1/telegram-send

Body:

{
 "to": "telegram_chat_id",
 "message": "Hello via Telegram!",
 "conversationId": "conv-uuid"
}

TikTok - Send Message¶

Endpoint: POST /functions/v1/tiktok-send

Body:

{
 "to": "tiktok_user_id",
 "message": "Hello via TikTok!",
 "conversationId": "conv-uuid"
}

Search & Utilities¶

Search Contacts¶

Endpoint: POST /functions/v1/search-contacts

Headers:

Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json

Body:

{
 "searchTerm": "John",
 "tags": ["customer", "vip"],
 "dealStatus": "open"
}

Response:

{
 "contacts": [
 {
 "id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer"]
 }
 ],
 "count": 1
}

Search Companies¶

Endpoint: POST /functions/v1/search-companies

Body:

{
 "searchTerm": "Acme",
 "country": "US"
}

List Organizations¶

Endpoint: GET /functions/v1/list-organizations

Response:

{
 "organizations": [
 {
 "id": "uuid",
 "name": "Organization Name",
 "suitId": "YOUR_SUIT_ID",
 "hasAppgainCredentials": true
 }
 ],
 "count": 1
}

Payments¶

Create Stripe Checkout¶

Endpoint: POST /functions/v1/create-checkout

Body:

{
 "priceId": "price_xxxxx",
 "couponCode": "optional_coupon"
}

Get Customer Portal URL¶

Endpoint: GET /functions/v1/customer-portal

Response:

{
 "url": "https://billing.stripe.com/p portal/..."
}

External APIs¶

These APIs use X-API-Key header for authentication and are designed for external systems to integrate with ConnectGain.

Insert Message¶

Endpoint: POST /functions/v1/insert-message

Headers:

X-API-Key: cg_abc123def456...
Content-Type: application/json

Body:

{
 "phone": "201001383533",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
}

Curl:

curl -X POST \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/insert-message' \
 -H 'X-API-Key: cg_abc123def456...' \
 -H 'Content-Type: application/json' \
 -d '{
 "phone": "201001383533",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
 }'

Response:

{
 "success": true,
 "messageId": "message-uuid",
 "conversationId": "conversation-uuid",
 "contactId": "contact-uuid"
}

Description: Inserts a message into the ConnectGain system. The system will: - Find or create a contact based on the phone number - Find or create a conversation for the contact - Insert the message with the specified direction and status

Parameters: - phone (required): Phone number in international format (e.g., "201001383533") - content (required): Message content/text - direction (required): Message direction - "incoming" or "outgoing" - status (required): Message status - "sent", "received", "delivered", "failed", etc.

Generate API Key¶

Endpoint: POST /functions/v1/generate-api-key

Headers:

Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json

Body:

{
 "name": "External System Integration",
 "organizationId": "org-uuid"
}

Curl:

curl -X POST \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/generate-api-key' \
 -H 'Authorization: Bearer YOUR_ANON_KEY' \
 -H 'Content-Type: application/json' \
 -d '{
 "name": "External System Integration",
 "organizationId": "org-uuid"
 }'

Response:

{
 "success": true,
 "api_key": "cg_abc123def456...",
 "key_info": {
 "id": "key-uuid",
 "name": "External System Integration",
 "key_prefix": "cg_abc123",
 "expires_at": null,
 "created_at": "2025-01-15T10:30:00Z"
 },
 "warning": "Store this key now — it will not be shown again."
}

Description: Creates a new API key for your organization. API keys are prefixed with cg_ and can be used with external APIs that require X-API-Key header authentication.

Important: Store the API key securely immediately after creation, as it will not be shown again.

Parameters: - name (required): Descriptive name for the API key (e.g., "Production API", "Development Integration") - organizationId (required): Your organization UUID

REST API - Contacts¶

List All Contacts¶

Endpoint: GET /rest/v1/contacts

Query Parameters: - select=* - Select all fields - limit=100 - Limit results - offset=0 - Pagination - organization_id=eq.{org_id} - Filter by organization

Curl:

curl -X GET "https://txpaxbxhnvnhsjwwaeoy.supabase.co/rest/v1/contacts?select=*" \
 -H "apikey: YOUR_ANON_KEY" \
 -H "Authorization: Bearer YOUR_ANON_KEY"

Response:

[
 {
 "id": "uuid",
 "organization_id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer"],
 "custom_fields": {},
 "opt_in_status": true,
 "created_at": "2025-01-01T00:00:00Z",
 "updated_at": "2025-01-01T00:00:00Z"
 }
]

Get Single Contact¶

Endpoint: GET /rest/v1/contacts?id=eq.{contact_id}

Create Contact¶

Endpoint: POST /rest/v1/contacts

Body:

{
 "organization_id": "org-uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer", "vip"],
 "custom_fields": {
 "company": "Acme Inc",
 "position": "Manager"
 },
 "opt_in_status": true
}

Update Contact¶

Endpoint: PATCH /rest/v1/contacts?id=eq.{contact_id}

Body:

{
 "first_name": "Jane",
 "last_name": "Smith",
 "tags": ["customer", "vip", "priority"]
}

Delete Contact¶

Endpoint: DELETE /rest/v1/contacts?id=eq.{contact_id}

Search Contacts¶

Endpoint: GET /rest/v1/contacts?first_name=ilike.*John*

REST API - Deals/Leads¶

List All Deals¶

Endpoint: GET /rest/v1/deals

With Relations:

GET /rest/v1/deals?select=*,contacts(*),profiles!deals_owner_id_fkey(*)

Get Single Deal¶

Endpoint: GET /rest/v1/deals?id=eq.{deal_id}

Create Deal (Lead)¶

Endpoint: POST /rest/v1/deals

Body:

{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "pipeline_id": "pipeline-uuid",
 "title": "New Lead - John Doe",
 "stage": "lead",
 "value": 5000,
 "probability": 10,
 "expected_close_date": "2025-02-15",
 "custom_fields": {
 "source": "website",
 "priority": "high"
 }
}

Update Deal Stage¶

Endpoint: PATCH /rest/v1/deals?id=eq.{deal_id}

Body:

{
 "stage": "qualified",
 "probability": 50,
 "value": 7500
}

Delete Deal¶

Endpoint: DELETE /rest/v1/deals?id=eq.{deal_id}

Filter Deals by Stage¶

Endpoint: GET /rest/v1/deals?stage=eq.lead

REST API - Conversations¶

List All Conversations¶

Endpoint: GET /rest/v1/conversations

With Relations:

GET /rest/v1/conversations?select=*,contacts(*),channel_accounts(*),profiles!conversations_assignee_id_fkey(*)

Get Single Conversation¶

Endpoint: GET /rest/v1/conversations?id=eq.{conversation_id}

Create Conversation¶

Endpoint: POST /rest/v1/conversations

Body:

{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "channel_account_id": "channel-uuid",
 "status": "OPEN",
 "tags": ["urgent", "customer"]
}

Update Conversation¶

Endpoint: PATCH /rest/v1/conversations?id=eq.{conversation_id}

Body:

{
 "status": "CLOSED",
 "assignee_id": "user-uuid"
}

Assign Conversation¶

Endpoint: PATCH /rest/v1/conversations?id=eq.{conversation_id}

Body:

{
 "assignee_id": "user-uuid"
}

Delete Conversation¶

Endpoint: DELETE /rest/v1/conversations?id=eq.{conversation_id}

Filter Open Conversations¶

Endpoint: GET /rest/v1/conversations?status=eq.OPEN

REST API - Messages¶

List Messages for Conversation¶

Endpoint: GET /rest/v1/messages?conversation_id=eq.{conversation_id}

Ordered:

GET /rest/v1/messages?conversation_id=eq.{conversation_id}&order=created_at.asc

Create Message¶

Endpoint: POST /rest/v1/messages

Body:

{
 "organization_id": "org-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "direction": "OUTBOUND",
 "content": "Hello! This is a test message.",
 "status": "SENT",
 "metadata": {
 "sender_name": "AIBot"
 }
}

Update Message Status¶

Endpoint: PATCH /rest/v1/messages?id=eq.{message_id}

Body:

{
 "status": "DELIVERED"
}

Delete Message¶

Endpoint: DELETE /rest/v1/messages?id=eq.{message_id}

REST API - Tasks¶

List All Tasks¶

Endpoint: GET /rest/v1/tasks

With Relations:

GET /rest/v1/tasks?select=*,contacts(*)

Filter Incomplete:

GET /rest/v1/tasks?completed=eq.false

Create Task¶

Endpoint: POST /rest/v1/tasks

Body:

{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "title": "Follow up with customer",
 "description": "Call to discuss pricing",
 "due_date": "2025-01-30T12:00:00Z",
 "completed": false
}

Mark Task Complete¶

Endpoint: PATCH /rest/v1/tasks?id=eq.{task_id}

Body:

{
 "completed": true
}

Delete Task¶

Endpoint: DELETE /rest/v1/tasks?id=eq.{task_id}

Error Responses¶

400 Bad Request:

{
 "message": "Error message",
 "details": "Detailed error information"
}

401 Unauthorized:

{
 "message": "JWT expired"
}

403 Forbidden:

{
 "message": "Invalid API key"
}

404 Not Found:

{
 "message": "Could not find resource"
}

500 Internal Server Error:

{
 "message": "Internal server error",
 "error": "Error details"
}

Postman Collection¶

Import the Postman collection from: docs/ConnectGain_Postman_Collection.json

Setting Up Variables¶

Import collection into Postman
Set collection variables:
url: https://txpaxbxhnvnhsjwwaeoy.supabase.co
anon_key: Your Supabase anon key
api_key: Your ConnectGain API key (for external APIs)
organization_id: Your organization UUID
contact_id: Test contact ID
deal_id: Test deal ID
conversation_id: Test conversation ID
message_id: Test message ID
suit_id: Your Appgain Suit ID
Start testing APIs!

Complete CRUD Examples¶

Complete Contact Workflow¶

# 1. List contacts
curl -X GET "{{url}}/rest/v1/contacts" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}"

# 2. Create contact
curl -X POST "{{url}}/rest/v1/contacts" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{"organization_id": "{{organization_id}}", "first_name": "John", "last_name": "Doe"}'

# 3. Update contact (use contact_id from step 2)
curl -X PATCH "{{url}}/rest/v1/contacts?id=eq.CONTACT_UUID" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{"first_name": "Jane"}'

# 4. Delete contact
curl -X DELETE "{{url}}/rest/v1/contacts?id=eq.CONTACT_UUID" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}"

Complete Deal Workflow¶

# 1. Create deal
curl -X POST "{{url}}/rest/v1/deals" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{
 "organization_id": "{{organization_id}}",
 "contact_id": "{{contact_id}}",
 "pipeline_id": "{{pipeline_id}}",
 "title": "New Deal",
 "stage": "lead",
 "value": 5000
 }'

# 2. Move deal to qualified
curl -X PATCH "{{url}}/rest/v1/deals?id=eq.DEAL_UUID" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{"stage": "qualified", "probability": 50}'

# 3. Close as won
curl -X PATCH "{{url}}/rest/v1/deals?id=eq.DEAL_UUID" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{"stage": "closed_won", "probability": 100}'

External System Integration Example¶

# 1. Create API key
curl -X POST "{{url}}/functions/v1/generate-api-key" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{
 "name": "External System Integration",
 "organizationId": "{{organization_id}}"
 }'

# 2. Use API key to insert message
curl -X POST "{{url}}/functions/v1/insert-message" \
 -H "X-API-Key: cg_abc123def456..." \
 -H "Content-Type: application/json" \
 -d '{
 "phone": "201001383533",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
 }'

Notes¶

All timestamps are in ISO 8601 format
JSONB fields support nested objects
Arrays (tags, phones, emails) work with standard JSON arrays
Relations can be fetched using select parameter
Filtering uses PostgREST syntax: column=eq.value
Supports order, limit, offset for pagination
API keys are prefixed with cg_ and should be kept secure
External APIs (using X-API-Key) are scoped to the organization that created the key

Complete Documentation: See WHATSAPP_LITE_API_GUIDE.md for detailed WhatsApp Lite edge functions documentation.