CtrlLane API

# CtrlLane beginner examples
#
# Run one section at a time. Commands use curl and jq and call the same v1 API
# used by the CtrlLane console. Sending a message or starting a call is a
# real, billable action. Use your own authorised test number.

## 1. Check access
# Confirm that the key and Business ID work.
# Required permissions: channels:read
# Result: Returns WhatsApp, Voice, and Instagram messaging as live channels. SMS remains reserved until its provider route is enabled.
# Run this in Terminal. Replace the API key and test mobile number.
command -v jq >/dev/null || { echo "Install jq first: https://jqlang.org/download/"; exit 1; }
export CP_BASE_URL="https://app.ctrllane.com"
read -rsp "Paste your CtrlLane API key: " CP_API_KEY; echo
export CP_API_KEY
export CP_BUSINESS_ID="paste_business_id_here"
export CP_TEST_MOBILE="+919999999999"

curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/channels?businessId=$CP_BUSINESS_ID" \
  -H "Authorization: Bearer $CP_API_KEY" | jq

## 2. Create a contact
# Save a mobile-first customer in the native Contacts data source.
# Required permissions: contacts:write
# Result: Prints the new contact ID. Re-running the same commands is safe.
# Run this in Terminal. Replace the API key and test mobile number.
command -v jq >/dev/null || { echo "Install jq first: https://jqlang.org/download/"; exit 1; }
export CP_BASE_URL="https://app.ctrllane.com"
read -rsp "Paste your CtrlLane API key: " CP_API_KEY; echo
export CP_API_KEY
export CP_BUSINESS_ID="paste_business_id_here"
export CP_TEST_MOBILE="+919999999999"

# Contacts always belong to a category. This creates or reuses "API leads".
CATEGORY_ID=$(curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/contacts/categories" -X POST \
  -H "Authorization: Bearer $CP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: beginner-api-leads-category-v1" \
  -d "$(jq -n --arg businessId "$CP_BUSINESS_ID" \
    '{businessId: $businessId, name: "API leads"}')" | jq -er '.data.category.id')

CONTACT_ID=$(curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/contacts" -X POST \
  -H "Authorization: Bearer $CP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: beginner-contact-${CP_TEST_MOBILE//[^0-9]/}-v1" \
  -d "$(jq -n \
    --arg businessId "$CP_BUSINESS_ID" \
    --arg mobile "$CP_TEST_MOBILE" \
    --arg categoryId "$CATEGORY_ID" \
    '{businessId: $businessId, name: "API test contact", mobile: $mobile, categoryIds: [$categoryId]}')" \
  | jq -er '.data.contact.id')

echo "Contact created: $CONTACT_ID"

## 3. Send WhatsApp
# Find the connected number, send one message, and print its ID.
# Required permissions: channels:read, communications:write
# Result: Queues one real WhatsApp message. The same idempotency key never sends it twice.
# Run this in Terminal. Replace the API key and test mobile number.
command -v jq >/dev/null || { echo "Install jq first: https://jqlang.org/download/"; exit 1; }
export CP_BASE_URL="https://app.ctrllane.com"
read -rsp "Paste your CtrlLane API key: " CP_API_KEY; echo
export CP_API_KEY
export CP_BUSINESS_ID="paste_business_id_here"
export CP_TEST_MOBILE="+919999999999"

# CtrlLane discovers the Meta phone-number ID for this business.
PHONE_NUMBER_ID=$(curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/channels/assignments?businessId=$CP_BUSINESS_ID&channel=whatsapp" \
  -H "Authorization: Bearer $CP_API_KEY" | jq -er '.data.phoneNumberId')

MESSAGE_ID=$(curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/messages" -X POST \
  -H "Authorization: Bearer $CP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: beginner-whatsapp-${CP_TEST_MOBILE//[^0-9]/}-v1" \
  -d "$(jq -n \
    --arg businessId "$CP_BUSINESS_ID" \
    --arg phoneNumberId "$PHONE_NUMBER_ID" \
    --arg to "$CP_TEST_MOBILE" \
    '{businessId: $businessId, phoneNumberId: $phoneNumberId, to: $to, type: "text", text: "Hello from CtrlLane."}')" \
  | jq -er '.data.messageId')

echo "Message queued: $MESSAGE_ID"

## 4. Start a voice call
# Find a compatible Voice agent and call the test number.
# Required permissions: agents:read, voice:write
# Result: Starts one real call and prints its call ID. Calling requires an active Voice agent and approved number.
# Run this in Terminal. Replace the API key and test mobile number.
command -v jq >/dev/null || { echo "Install jq first: https://jqlang.org/download/"; exit 1; }
export CP_BASE_URL="https://app.ctrllane.com"
read -rsp "Paste your CtrlLane API key: " CP_API_KEY; echo
export CP_API_KEY
export CP_BUSINESS_ID="paste_business_id_here"
export CP_TEST_MOBILE="+919999999999"

# Choose the newest active Voice agent that does not require contact variables.
AGENT_ID=$(curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/agents?businessId=$CP_BUSINESS_ID" \
  -H "Authorization: Bearer $CP_API_KEY" \
  | jq -er '[.data.agents[] | select(.channel == "voice" and .status == "active" and .contactContextRequired == false)] | first | .id')

CALL_ID=$(curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/voice/calls" -X POST \
  -H "Authorization: Bearer $CP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: beginner-call-${CP_TEST_MOBILE//[^0-9]/}-v1" \
  -d "$(jq -n \
    --arg businessId "$CP_BUSINESS_ID" \
    --arg agentId "$AGENT_ID" \
    --arg toNumber "$CP_TEST_MOBILE" \
    '{businessId: $businessId, agentId: $agentId, toNumber: $toNumber}')" \
  | jq -er '.data.callId')

echo "Call started: $CALL_ID"

## 5. Read contact history
# Find a contact and read its WhatsApp and Voice timeline.
# Required permissions: contacts:read, communications:read
# Result: Returns the newest messages, transcripts, and call outcomes stored for that contact.
# Run this in Terminal. Replace the API key and test mobile number.
command -v jq >/dev/null || { echo "Install jq first: https://jqlang.org/download/"; exit 1; }
export CP_BASE_URL="https://app.ctrllane.com"
read -rsp "Paste your CtrlLane API key: " CP_API_KEY; echo
export CP_API_KEY
export CP_BUSINESS_ID="paste_business_id_here"
export CP_TEST_MOBILE="+919999999999"

CONTACT_ID=$(curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/contacts?businessId=$CP_BUSINESS_ID&search=${CP_TEST_MOBILE//+/%2B}" \
  -H "Authorization: Bearer $CP_API_KEY" \
  | jq -er '.data.contacts | first | .id')

curl --fail-with-body --silent --show-error \
  "$CP_BASE_URL/api/v1/contacts/$CONTACT_ID/timeline?businessId=$CP_BUSINESS_ID" \
  -H "Authorization: Bearer $CP_API_KEY" | jq