PlaceCall

Visão Geral

PlaceCall é uma API hospedada que realiza uma chamada telefônica real para uma empresa nos EUA, tem um agente de voz com IA que executa uma tarefa em linguagem simples nessa chamada (uma consulta, uma reserva, um cancelamento, um orçamento) e retorna um resultado estruturado, a transcrição e a gravação. O agente navega por menus telefônicos e espera, e pode enviar uma pergunta ao usuário no meio de uma chamada. Quando o usuário não tem um número, a API pode primeiro sugerir empresas para ligar e escrever o resumo da chamada para cada uma. Esta habilidade ensina um agente a usar essa API com curl. Adaptado da habilidade oficial PlaceCall: https://github.com/voygr-tech/placecall

Quando Usar Esta Habilidade

• Use quando o usuário pedir para você ligar para uma empresa, ou para perguntar, reservar, confirmar, reagendar ou cancelar algo por telefone, e o número for um número dos EUA.
• Use quando o usuário nomear uma necessidade em vez de um número ("encontre uma floricultura em Chicago com peônias e ligue para eles"): sugira lugares primeiro, depois ligue para o que o usuário escolher.
• Use quando o usuário pedir o status, resultado ou transcrição de uma chamada feita anteriormente, ou quiser responder a uma pergunta que o agente de chamada enviou no meio da chamada.
• Não use para SMS, e-mail, números que não sejam dos EUA ou números para os quais o usuário não tem permissão para ligar.

Como Funciona

Todas as requisições vão para https://api.voygr.tech via HTTPS com o cabeçalho X-API-Key: $PLACECALL_API_KEY.

Etapa 1: Verificar a chave e o saldo

O usuário cria uma chave em https://api.voygr.tech/checkout (nome e e-mail; a chave é enviada por e-mail) e a coloca na variável de ambiente PLACECALL_API_KEY ou nas configurações seguras do agente. Nunca peça a chave no chat, nunca a imprima e nunca procure no disco por arquivos de credenciais.

curl -s -H "X-API-Key: $PLACECALL_API_KEY" https://api.voygr.tech/users/me
# 200 {"customer_id":"...","credits_available":...,"max_concurrent_calls":...}

Etapa 2: Escrever o resumo e confirmá-lo

O agente de chamada lê apenas o brief. Coloque todos os detalhes nele: o que perguntar, em nome de quem você está ligando (não há um campo separado para nome do chamador), nomes, datas, tamanho do grupo, um número de retorno de chamada e como encerrar. Mostre ao usuário o número e o resumo e obtenha um "sim" antes de discar.

Etapa 3: Realizar a chamada

Gere um novo UUID para Idempotency-Key para cada chamada que você pretende fazer e mantenha-o com essa chamada.

curl -s -X POST https://api.voygr.tech/calls \
  -H "X-API-Key: $PLACECALL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c2a0e-0b8e-4c55-9a51-2d7d1f0b6c11" \
  -d '{
        "target_phone": "+15551234567",
        "brief": "Call this sports bar and find out (1) whether they are showing the USA vs Netherlands match today and (2) whether a reservation is needed. Read the answers back to confirm, thank them, and end.",
        "language": "en",
        "ask_user_mode": "stream"
      }'
# -> 201 {"call":{"call_id":"...","status":"dialing",...},...}

• target_phone: E.164 (+1...). 911 e outros códigos N11 são recusados com 422.
• brief: até 4000 caracteres.
• language: auto (resolve para en) ou um de en, es, fr, de, hi, ru, pt, ja, it, nl, sr, tr, pl. Qualquer outra coisa retorna 422 unsupported_language.
• ask_user_mode: sempre envie "stream", para que perguntas no meio da chamada cheguem ao feed de eventos que você consulta.
• O ID da chamada é aninhado: call.call_id. Algumas implementações respondem a 202 com status: "queued"; siga da mesma forma.

Para reservas, o caminho estruturado opcional valida os detalhes antes de qualquer discagem: envie "intent": "booking" com slots (target_phone, name, date como YYYY-MM-DD, time como HH:MM, party_size, phone_to_dictate opcional) em vez de um brief. Uma lacuna retorna como 422 missing_slots com um suggested_question para cada campo ausente. Este caminho retorna um call_id plano. Envie um brief ou intent + slots, nunca ambos.

Etapa 4: Acompanhar a chamada consultando eventos

Consulte; não mantenha um fluxo curl -N de longa duração aberto. Use o parâmetro de consulta after_event_id.

ID=<call_id>; LAST=0; STOP=$(($(date +%s)+120))
while [ "$(date +%s)" -lt "$STOP" ]; do
  OUT=$(curl -s --max-time 20 -H "X-API-Key: $PLACECALL_API_KEY" \
        "https://api.voygr.tech/calls/$ID/events?after_event_id=$LAST")
  [ -n "$OUT" ] && echo "$OUT"
  N=$(printf '%s' "$OUT" | sed -n 's/^id: //p' | tail -1); [ -n "$N" ] && LAST=$N
  printf '%s' "$OUT" | grep -q '^event: outcome'  && { echo "### OUTCOME ###"; break; }

…