Developer documentation

curl https://api.phonevoice.ai/api/whoami \
  -H "Authorization: Bearer YOUR_TOKEN"

const res = await fetch("https://api.phonevoice.ai/api/whoami", {
  headers: { Authorization: "Bearer YOUR_TOKEN" }
});
console.log(await res.json());

import requests

r = requests.get(
    "https://api.phonevoice.ai/api/whoami",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)
print(r.json())

require "net/http"
require "json"

uri = URI("https://api.phonevoice.ai/api/whoami")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)

curl -X POST https://api.phonevoice.ai/api/v1/calls/initiate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 1533,
    "recipient_phone_number": "+33612345678",
    "inbound_phone_number": "+33159133354",
    "enable_recording": true,
    "enable_transcription": true,
    "enable_analysis": true
  }'

const res = await fetch("https://api.phonevoice.ai/api/v1/calls/initiate", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: 1533,
    recipient_phone_number: "+33612345678",
    inbound_phone_number: "+33159133354",
    enable_recording: true,
    enable_transcription: true,
    enable_analysis: true,
  }),
});
const call = await res.json();
console.log(call.phone_call_id);

import requests

res = requests.post(
    "https://api.phonevoice.ai/api/v1/calls/initiate",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "agent_id": 1533,
        "recipient_phone_number": "+33612345678",
        "inbound_phone_number": "+33159133354",
        "enable_recording": True,
        "enable_transcription": True,
        "enable_analysis": True,
    },
)
print(res.json()["phone_call_id"])

require "net/http"
require "json"

uri = URI("https://api.phonevoice.ai/api/v1/calls/initiate")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
req["Content-Type"] = "application/json"
req.body = {
  agent_id: 1533,
  recipient_phone_number: "+33612345678",
  inbound_phone_number: "+33159133354",
  enable_recording: true,
  enable_transcription: true,
  enable_analysis: true,
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)["phone_call_id"]

curl -X POST https://api.phonevoice.ai/api/v1/calls/initiate \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{ "call_type":"bridge", "vendeur_mode":"browser",
        "recipient_phone_number":"+33612345678" }'
# => 201 { "phone_call_id": 90210, "cable_token": "…" }

const API = "https://api.phonevoice.ai/api/v1";
const headers = { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json" };

// Start a bridge call (browser mode)
const { phone_call_id, cable_token } = await fetch(`${API}/calls/initiate`, {
  method: "POST", headers,
  body: JSON.stringify({ call_type: "bridge", vendeur_mode: "browser", recipient_phone_number: "+33612345678" }),
}).then(r => r.json());

import requests
API = "https://api.phonevoice.ai/api/v1"
headers = {"Authorization": "Bearer YOUR_TOKEN"}

# Start a bridge call (browser mode)
call = requests.post(f"{API}/calls/initiate", headers=headers, json={
    "call_type": "bridge", "vendeur_mode": "browser",
    "recipient_phone_number": "+33612345678",
}).json()
# call["phone_call_id"], call["cable_token"]

require "faraday"
require "json"

conn = Faraday.new("https://api.phonevoice.ai/api/v1") do |f|
  f.headers["Authorization"] = "Bearer YOUR_TOKEN"
  f.headers["Content-Type"] = "application/json"
end

call = JSON.parse(conn.post("calls/initiate",
  { call_type: "bridge", vendeur_mode: "browser", recipient_phone_number: "+33612345678" }.to_json).body)
# call["phone_call_id"], call["cable_token"]

curl -X POST https://api.phonevoice.ai/api/v1/calls/90210/embed_session \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{ "role":"agent" }'
# => { "embed_url":"https://api.phonevoice.ai/embed?t=…", "role":"agent", "expires_in":300 }

const { embed_url } = await fetch("https://api.phonevoice.ai/api/v1/calls/90210/embed_session", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({ role: "agent" }),
}).then(r => r.json());

const iframe = Object.assign(document.createElement("iframe"), { src: embed_url, allow: "microphone; autoplay" });
document.body.appendChild(iframe);

import requests
session = requests.post("https://api.phonevoice.ai/api/v1/calls/90210/embed_session",
    headers={"Authorization": "Bearer YOUR_TOKEN"}, json={"role": "agent"}).json()
print(session["embed_url"])  # hand this URL to a browser to embed

require "faraday"
require "json"

res = Faraday.post("https://api.phonevoice.ai/api/v1/calls/90210/embed_session",
  { role: "agent" }.to_json,
  { "Authorization" => "Bearer YOUR_TOKEN", "Content-Type" => "application/json" })
puts JSON.parse(res.body)["embed_url"]  # hand this URL to a browser to embed

# 1. Search available US numbers
curl "https://api.phonevoice.ai/api/v1/relay_numbers/available?country=US&type=local&area_code=415" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 2. Buy one and forward it to your phone
curl -X POST https://api.phonevoice.ai/api/v1/relay_numbers \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{ "phone_number":"+14155550123", "forward_to":"+33612345678", "country":"US" }'

# 3. Later — change the destination or pause it
curl -X PATCH https://api.phonevoice.ai/api/v1/relay_numbers/123 \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{ "forward_to":"+33700000000", "relay_enabled": true }'

const API = "https://api.phonevoice.ai/api/v1";
const headers = { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json" };

// 1. Search available numbers
const avail = await fetch(`${API}/relay_numbers/available?country=US&type=local&area_code=415`, { headers });

// 2. Buy + forward to your phone
const num = await fetch(`${API}/relay_numbers`, {
  method: "POST", headers,
  body: JSON.stringify({ phone_number: "+14155550123", forward_to: "+33612345678", country: "US" }),
}).then(r => r.json());

// 3. Update the destination / pause
await fetch(`${API}/relay_numbers/${num.id}`, {
  method: "PATCH", headers,
  body: JSON.stringify({ forward_to: "+33700000000", relay_enabled: true }),
});

import requests

API = "https://api.phonevoice.ai/api/v1"
headers = {"Authorization": "Bearer YOUR_TOKEN"}

# 1. Search available numbers
requests.get(f"{API}/relay_numbers/available",
             params={"country": "US", "type": "local", "area_code": "415"}, headers=headers)

# 2. Buy + forward to your phone
num = requests.post(f"{API}/relay_numbers", headers=headers,
    json={"phone_number": "+14155550123", "forward_to": "+33612345678", "country": "US"}).json()

# 3. Update the destination / pause
requests.patch(f"{API}/relay_numbers/{num['id']}", headers=headers,
    json={"forward_to": "+33700000000", "relay_enabled": True})

require "faraday"
require "json"

conn = Faraday.new("https://api.phonevoice.ai/api/v1") do |f|
  f.headers["Authorization"] = "Bearer YOUR_TOKEN"
  f.headers["Content-Type"] = "application/json"
end

# 1. Search available numbers
conn.get("relay_numbers/available", country: "US", type: "local", area_code: "415")

# 2. Buy + forward to your phone
num = JSON.parse(conn.post("relay_numbers",
  { phone_number: "+14155550123", forward_to: "+33612345678", country: "US" }.to_json).body)

# 3. Update the destination / pause
conn.patch("relay_numbers/#{num['id']}",
  { forward_to: "+33700000000", relay_enabled: true }.to_json)

curl -X POST https://api.phonevoice.ai/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{ "url":"https://example.com/hooks/phonevoice",
        "events":["phone_call.completed","sms.received"], "name":"My CRM" }'

const res = await fetch("https://api.phonevoice.ai/api/v1/webhooks", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com/hooks/phonevoice",
    events: ["phone_call.completed", "sms.received"],
    name: "My CRM",
  }),
});
const { secret } = await res.json(); // store this — shown only once

import requests

res = requests.post(
    "https://api.phonevoice.ai/api/v1/webhooks",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "url": "https://example.com/hooks/phonevoice",
        "events": ["phone_call.completed", "sms.received"],
        "name": "My CRM",
    },
)
secret = res.json()["secret"]  # store this — shown only once

require "net/http"
require "json"

uri = URI("https://api.phonevoice.ai/api/v1/webhooks")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
req["Content-Type"] = "application/json"
req.body = {
  url: "https://example.com/hooks/phonevoice",
  events: ["phone_call.completed", "sms.received"],
  name: "My CRM",
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
secret = JSON.parse(res.body)["secret"] # store this — shown only once

// Node.js (Express) — verify before trusting the payload
const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

# Python (Flask) — verify before trusting the payload
import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=") for p in header.split(","))
    expected = hmac.new(secret.encode(),
                        f"{parts['t']}.{raw_body.decode()}".encode(),
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

# Ruby (Rails) — verify before trusting the payload
require "openssl"

def verify(raw_body, header, secret)
  parts = header.split(",").map { |p| p.split("=") }.to_h
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{parts['t']}.#{raw_body}")
  Rack::Utils.secure_compare(expected, parts["v1"])
end

// Browser — subscribe to the live transcript over ActionCable
const cable = new WebSocket("wss://api.phonevoice.ai/cable");
const identifier = JSON.stringify({ channel: "CallsChannel", id: 90210, token: "CABLE_TOKEN" });

cable.onopen = () => cable.send(JSON.stringify({ command: "subscribe", identifier }));

cable.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (!msg.message) return;            // welcome / ping / confirm_subscription
  const m = msg.message;
  if (m.type === "transcript") console.log(`${m.role}: ${m.content}`);
  if (m.type === "status_changed") console.log("status:", m.status);
};

# pip install websocket-client
import json, websocket

ws = websocket.create_connection("wss://api.phonevoice.ai/cable")
identifier = json.dumps({"channel": "CallsChannel", "id": 90210, "token": "CABLE_TOKEN"})
ws.send(json.dumps({"command": "subscribe", "identifier": identifier}))

while True:
    m = json.loads(ws.recv()).get("message")
    if not m:                          # welcome / ping / confirm_subscription
        continue
    if m["type"] == "transcript":
        print(m["role"], ":", m["content"])
    elif m["type"] == "status_changed":
        print("status:", m["status"])