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
​
search
string
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