WhatsApp calling for partners

Sandbox:   https://sandbox.voice.miraiminds.co
Production: https://prod.voice.miraiminds.co

set -euo pipefail

curl --fail-with-body "$VOICE_BASE_URL/v2/wallet" \
  -H "Authorization: Bearer $VOICE_API_KEY"

curl --fail-with-body "$VOICE_BASE_URL/v2/voices" \
  -H "Authorization: Bearer $VOICE_API_KEY"

brand_id → workspace_id, business_number, phone_number_id,
           agent_id, number_id, number_version, enabled

{
  "name": "WhatsApp Calling Test",
  "system_prompt": "You are Mira, a voice agent running a short WhatsApp voice-call test. Clearly say this is a test. Start in English and switch to Hindi or Hinglish if the caller prefers. Ask whether they can hear you clearly, listen to a short reply, and repeat its main point to confirm two-way audio. Keep replies brief and natural. Do not claim to access orders, customer records, payments, or other business systems. If asked about this test, explain that it checks whether a WhatsApp call can connect to a voice agent and carry audio in both directions. When the caller wants to finish, thank them and end the call.",
  "first_message": "Hello! I am Mira, the voice agent for this WhatsApp calling test. Can you hear me clearly?",
  "voice": {"voice_id": "neha", "language": "en"},
  "language": "en",
  "max_duration_secs": 120
}

jq -n --arg ws "$VOICE_WORKSPACE_ID" --arg agent "$AGENT_ID" '{
  calling: {
    status: "ENABLED",
    srtp_key_exchange_protocol: "SDES",
    audio: {additional_codecs: ["PCMA", "PCMU"]},
    sip: {
      status: "ENABLED",
      servers: [{
        hostname: "sip.miraiminds.co",
        port: 5061,
        request_uri_user_params: {ws: $ws, agent: $agent}
      }]
    }
  }
}' > meta-settings.json

curl --fail-with-body -X POST \
  "https://graph.facebook.com/$META_GRAPH_VERSION/$PHONE_NUMBER_ID/settings" \
  -H "Authorization: Bearer $META_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @meta-settings.json

umask 077
curl --fail-with-body \
  "https://graph.facebook.com/$META_GRAPH_VERSION/$PHONE_NUMBER_ID/settings?include_sip_credentials=true" \
  -H "Authorization: Bearer $META_ACCESS_TOKEN" \
  --output meta-settings.private.json

umask 077
jq -e --arg number "$BUSINESS_NUMBER" --arg phone_id "$PHONE_NUMBER_ID" \
  --arg agent "$AGENT_ID" --arg webhook "$VOICE_WEBHOOK_URL" '
  [.calling.sip.servers[] | select(.hostname == "sip.miraiminds.co")
    | .sip_user_password | select(type == "string" and length > 0)] as $passwords
  | if ($passwords | length) != 1 then error("Expected one SIP password")
    else {
      business_number: $number,
      phone_number_id: $phone_id,
      agent_id: $agent,
      sip_username: $number,
      sip_password: $passwords[0],
      webhook_url: $webhook
    } end
' meta-settings.private.json > number.private.json

curl --fail-with-body -X POST "$VOICE_BASE_URL/v2/whatsapp/numbers" \
  -H "Authorization: Bearer $VOICE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: partner:$BRAND_ID:number:v1" \
  --data-binary @number.private.json --output number.created.json

NUMBER_ID=$(jq -er '.id' number.created.json)

{
  "id": "wan_EXAMPLE",
  "business_number": "+919876543210",
  "phone_number_id": "123456789012345",
  "agent_id": "agt_EXAMPLE",
  "state": "pending",
  "version": 1,
  "sip_password_set": true,
  "sip": {
    "hostname": "sip.miraiminds.co",
    "port": 5061,
    "request_uri_user_params": {"ws": "ws_EXAMPLE", "agent": "agt_EXAMPLE"}
  }
}

curl --fail-with-body "$VOICE_BASE_URL/v2/whatsapp/numbers/$NUMBER_ID" \
  -H "Authorization: Bearer $VOICE_API_KEY"

{
  "event": "call.resolve",
  "call_id": "call_EXAMPLE",
  "direction": "inbound",
  "from": "+919876543211",
  "to": "+919876543210"
}

{
  "allow": true,
  "variables": {
    "customer_name": "Asha",
    "support_context": "The customer requested help choosing a product."
  }
}

curl --fail-with-body \
  "https://graph.facebook.com/$META_GRAPH_VERSION/$PHONE_NUMBER_ID/call_permissions?user_wa_id=$CUSTOMER_WHATSAPP_DIGITS" \
  -H "Authorization: Bearer $META_ACCESS_TOKEN" \
  --output permission.json

jq -e '.actions | any(.action_name == "start_call" and .can_perform_action == true)' \
  permission.json

{
  "agent_id": "agt_YOUR_BRANDS_AGENT",
  "route": "whatsapp",
  "from": "+919876543210",
  "to": "+919876543211",
  "max_duration_secs": 120,
  "webhook_url": "https://your-backend.example/voice/events",
  "variables": {"customer_name": "Asha"},
  "metadata": {"brand_id": "your-brand-id", "callback_id": "your-callback-job-id"}
}

{
  "id": "evt_EXAMPLE",
  "type": "call.completed",
  "created_at": "2026-09-30T09:00:00Z",
  "data": {
    "call": {
      "id": "call_EXAMPLE",
      "agent_id": "agt_EXAMPLE",
      "route": "whatsapp",
      "direction": "outbound",
      "from": "+919876543210",
      "to": "+919876543211",
      "status": "completed"
    }
  }
}

import hashlib
import hmac
import re
import time

def verify_signature(secret: str, header: str, raw_body: bytes) -> None:
    parts = {}
    for item in header.split(","):
        key, separator, value = item.strip().partition("=")
        if not separator or key in parts:
            raise ValueError("Malformed signature")
        parts[key] = value
    timestamp, digest = parts.get("t", ""), parts.get("v1", "")
    if not secret or not re.fullmatch(r"[0-9]{1,12}", timestamp):
        raise ValueError("Missing secret or timestamp")
    if not re.fullmatch(r"[a-f0-9]{64}", digest):
        raise ValueError("Malformed digest")
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("Expired signature")
    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, digest):
        raise ValueError("Invalid signature")

{"version": 1, "webhook_url": "https://your-backend.example/voice/events"}