Pular para o conteúdo principal
GET
/
api
/
v1
/
phone-numbers
# Requisição 1: Obter todos os números de telefone
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers" \
  -H "Authorization: Bearer talq_your_environment_token_here"
{
  "success": true,
  "data": [
    {
      "id": "phone-uuid-1",
      "number": "+1234567890",
      "country_code": "US",
      "formatted_number": "(123) 456-7890",
      "international_number": "+1 234 567 890",
      "type": "voice",
      "has_voice": true,
      "has_sms": true,
      "has_mms": false,
      "has_fax": false,
      "has_whatsapp": false,
      "current_status": "active",
      "is_sandbox": false,
      "current_price": 1.00,
      "currency": "USD",
      "renewal_date": "2024-02-15",
      "auto_renewal": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "monthly_renewal_cost": 1.00,
      "days_until_monthly_renewal": 15,
      "is_due_for_monthly_renewal": false,
      "environment": null,
      "agents": null
    },
    {
      "id": "phone-uuid-2",
      "number": "+1987654321",
      "country_code": "US",
      "formatted_number": "(987) 654-3210",
      "international_number": "+1 987 654 321",
      "type": "voice",
      "has_voice": true,
      "has_sms": true,
      "has_mms": false,
      "has_fax": false,
      "has_whatsapp": false,
      "current_status": "active",
      "is_sandbox": false,
      "current_price": 1.00,
      "currency": "USD",
      "renewal_date": "2024-02-15",
      "auto_renewal": true,
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z",
      "monthly_renewal_cost": 1.00,
      "days_until_monthly_renewal": 15,
      "is_due_for_monthly_renewal": false,
      "environment": null,
      "agents": null
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

Listar Números de Telefone

Recuperar uma lista de números de telefone disponíveis com opções de filtragem por tipo, capacidades e status.

Endpoint

GET /api/v1/phone-numbers

Cabeçalhos da Requisição

Authorization
string
obrigatório
Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here

Parâmetros de Consulta

type
string
Filtrar por tipo de número de telefone. Opções: voice, sms, whatsapp, mms, fax
has_voice
boolean
Filtrar por capacidade de voz. Opções: true, false
has_whatsapp
boolean
Filtrar por capacidade de WhatsApp. Opções: true, false
Pesquisar por número de telefone ou ID

Exemplos de Requisição

# Requisição 1: Obter todos os números de telefone
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers" \
  -H "Authorization: Bearer talq_your_environment_token_here"
# Requisição 2: Obter números com capacidade de voz
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers?has_voice=true" \
  -H "Authorization: Bearer talq_your_environment_token_here"
# Requisição 3: Pesquisar por número específico
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers?search=+1234567890" \
  -H "Authorization: Bearer talq_your_environment_token_here"

Resposta

Resposta de Sucesso (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "phone-uuid-1",
      "number": "+1234567890",
      "country_code": "US",
      "formatted_number": "(123) 456-7890",
      "international_number": "+1 234 567 890",
      "type": "voice",
      "has_voice": true,
      "has_sms": true,
      "has_mms": false,
      "has_fax": false,
      "has_whatsapp": false,
      "current_status": "active",
      "is_sandbox": false,
      "current_price": 1.00,
      "currency": "USD",
      "renewal_date": "2024-02-15",
      "auto_renewal": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "monthly_renewal_cost": 1.00,
      "days_until_monthly_renewal": 15,
      "is_due_for_monthly_renewal": false,
      "environment": null,
      "agents": null
    },
    {
      "id": "phone-uuid-2",
      "number": "+1987654321",
      "country_code": "US",
      "formatted_number": "(987) 654-3210",
      "international_number": "+1 987 654 321",
      "type": "voice",
      "has_voice": true,
      "has_sms": true,
      "has_mms": false,
      "has_fax": false,
      "has_whatsapp": false,
      "current_status": "active",
      "is_sandbox": false,
      "current_price": 1.00,
      "currency": "USD",
      "renewal_date": "2024-02-15",
      "auto_renewal": true,
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z",
      "monthly_renewal_cost": 1.00,
      "days_until_monthly_renewal": 15,
      "is_due_for_monthly_renewal": false,
      "environment": null,
      "agents": null
    }
  ]
}

Campos da Resposta

success
boolean
obrigatório
Indica se a operação foi bem-sucedida.
data
array
obrigatório
Array de objetos de número de telefone.

Respostas de Erro

401 Não Autorizado

{
  "success": false,
  "message": "Unauthorized"
}

422 Erro de Validação

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "type": [
      "The selected type is invalid."
    ]
  }
}

500 Erro do Servidor

{
  "success": false,
  "message": "Internal server error."
}

Códigos de Erro

CódigoDescriçãoStatus HTTP
INVALID_TOKENToken de autenticação inválido ou ausente401
VALIDATION_ERRORValidação dos parâmetros de consulta falhou422
SERVER_ERRORErro interno do servidor ocorreu500

Notas Importantes

Capacidades de filtragem. Use parâmetros de consulta para filtrar números por tipo e capacidades.
Formato de números. Todos os números são retornados em formato E.164.
Informações de renovação. Inclui detalhes sobre custos e datas de renovação.

Melhores Práticas

  1. Filtre por capacidades - Use has_voice e has_whatsapp para encontrar números adequados
  2. Verifique status - Certifique-se de que os números estão ativos antes de usar
  3. Monitore renovação - Acompanhe as datas de renovação para evitar interrupções
  4. Pesquise eficientemente - Use o parâmetro search para encontrar números específicos
  5. Trate erros - Implemente tratamento adequado de erros para falhas de autenticação e validação

Endpoints Relacionados

  • Listar Modelos de Voz: GET /api/v1/voice-templates
  • Gerar Demonstração de Voz: GET /api/v1/voice-templates/{voice_template_id}/demo