KanutusDocs
kanutus.com Entrar / Criar contaEntrar

Ligações

GET/v1/calls/quote

Cotar um destino e conferir a finalidade da ligação naquele país

Permissão: calls:read

Parâmetros

NomeTipoDescrição
to obrigatórioquery · string
purposequery · "transactional" | "scheduling" | "support" | "marketing"
consentquery · "existing_customer" | "prior_express" | "written"
fromquery · string

Resposta 200

NomeTipoDescrição
to obrigatóriostringMasked number
country obrigatóriostring
kind obrigatóriostring
allowed obrigatórioboolean
minute_factor obrigatórionumber
reason obrigatóriostring
purpose obrigatórioobject | null
purpose.purpose obrigatório"transactional" | "scheduling" | "support" | "marketing"
purpose.allowed obrigatórioboolean
purpose.code obrigatóriostring
purpose.message obrigatóriostring | null
purpose.requires obrigatóriostring[]
purpose.legal_reviewed obrigatórioboolean
simulator obrigatóriostring | null

Exemplo

curl
curl "https://api.kanutus.com/v1/calls/quote?to=string" \
  -H "Authorization: Bearer $KANUTUS_API_KEY"
Testar agora

Roda no seu navegador contra a API de verdade. Use uma chave kt_test_: nada é cobrado. A chave fica só nesta aba.

GET /v1/calls/quote

Respostas por status

200 Destination, minute factor and whether this purpose is allowed there
200
{
  "to": "string",
  "country": "string",
  "kind": "string",
  "allowed": true,
  "minute_factor": 0,
  "reason": "string",
  "purpose": {
    "purpose": "transactional",
    "allowed": true,
    "code": "string",
    "message": "string",
    "requires": [
      "string"
    ],
    "legal_reviewed": true
  },
  "simulator": "string"
}
400 Invalid request
400 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

401 Missing, invalid, expired or revoked credential
401 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

403 Missing permission, blocked or not allowed
403 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)
429 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

POST/v1/calls

Fazer uma ligação traduzida como agente de IA (sempre se anuncia como IA) Em breve

Permissão: calls:dial

Em produção responde 501 (em breve). Já dá para testar com uma chave kt_test_ (simulador).

Parâmetros

NomeTipoDescrição
idempotency-key obrigatórioheader · stringUnique key per create request; retries with the same key return the same result.

Corpo da requisição

NomeTipoDescrição
to obrigatóriostringlength 4–32
fromstringCaller ID (one of the organization's numbers) · length 0–32
purpose obrigatório"transactional" | "scheduling" | "support" | "marketing"
consentobject
consent.kind obrigatório"existing_customer" | "prior_express" | "written"
consent.refstringYour reference to the consent record · length 0–200
agent_langstringdefault "en"
remote_langstring
voice_idstringlength 0–100

Resposta 201

NomeTipoDescrição
id obrigatóriostring
to obrigatóriostring
country obrigatóriostring
purpose obrigatório"transactional" | "scheduling" | "support" | "marketing"
status obrigatório"queued" | "ringing" | "answered" | "completed" | "busy" | "voicemail" | "no_answer" | "failed" | "blocked"
ai_disclosure obrigatóriotrue
billed_seconds obrigatóriointeger
created_at obrigatóriostring
answered_atstring | null
ended_atstring | null
end_reasonstring | nullagent_hangup, remote_hangup, max_duration, busy, voicemail, no_answer…
livemode obrigatórioboolean

Exemplo

curl
curl -X POST "https://api.kanutus.com/v1/calls" \
  -H "Authorization: Bearer $KANUTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"to":"+1 555 0100","from":"string","purpose":"transactional","consent":{"kind":"existing_customer","ref":"string"},"agent_lang":"en","remote_lang":"string","voice_id":"string"}'
Testar agora

Roda no seu navegador contra a API de verdade. Use uma chave kt_test_: nada é cobrado. A chave fica só nesta aba.

POST /v1/calls

Respostas por status

201 Call created
201
{
  "id": "string",
  "to": "string",
  "country": "string",
  "purpose": "transactional",
  "status": "queued",
  "ai_disclosure": true,
  "billed_seconds": 0,
  "created_at": "string",
  "answered_at": "string",
  "ended_at": "string",
  "end_reason": "string",
  "livemode": true
}
400 Invalid request
400 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

401 Missing, invalid, expired or revoked credential
401 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

402 Spend limit of this credential reached
402 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 402,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

403 Missing permission, blocked or not allowed
403 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

409 Conflict (idempotency or state)
409 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 409,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)
429 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

501 Not available yet in live mode (use a kt_test_ key)
501 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 501,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

GET/v1/calls

Ligações feitas por esta credencial

Permissão: calls:read

Resposta 200

NomeTipoDescrição
data obrigatórioobject[]
data[].id obrigatóriostring
data[].to obrigatóriostring
data[].country obrigatóriostring
data[].purpose obrigatório"transactional" | "scheduling" | "support" | "marketing"
data[].status obrigatório"queued" | "ringing" | "answered" | "completed" | "busy" | "voicemail" | "no_answer" | "failed" | "blocked"
data[].ai_disclosure obrigatóriotrue
data[].billed_seconds obrigatóriointeger
data[].created_at obrigatóriostring
data[].answered_atstring | null
data[].ended_atstring | null
data[].end_reasonstring | nullagent_hangup, remote_hangup, max_duration, busy, voicemail, no_answer…
data[].livemode obrigatórioboolean

Exemplo

curl
curl "https://api.kanutus.com/v1/calls" \
  -H "Authorization: Bearer $KANUTUS_API_KEY"
Testar agora

Roda no seu navegador contra a API de verdade. Use uma chave kt_test_: nada é cobrado. A chave fica só nesta aba.

GET /v1/calls

Respostas por status

200 Calls, newest first
200
{
  "data": [
    {
      "id": "string",
      "to": "string",
      "country": "string",
      "purpose": "transactional",
      "status": "queued",
      "ai_disclosure": true,
      "billed_seconds": 0,
      "created_at": "string",
      "answered_at": "string",
      "ended_at": "string",
      "end_reason": "string",
      "livemode": true
    }
  ]
}
400 Invalid request
400 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

401 Missing, invalid, expired or revoked credential
401 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

403 Missing permission, blocked or not allowed
403 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)
429 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

GET/v1/calls/{id}

Ler uma ligação

Permissão: calls:read

Parâmetros

NomeTipoDescrição
id obrigatóriopath · string

Resposta 200

NomeTipoDescrição
id obrigatóriostring
to obrigatóriostring
country obrigatóriostring
purpose obrigatório"transactional" | "scheduling" | "support" | "marketing"
status obrigatório"queued" | "ringing" | "answered" | "completed" | "busy" | "voicemail" | "no_answer" | "failed" | "blocked"
ai_disclosure obrigatóriotrue
billed_seconds obrigatóriointeger
created_at obrigatóriostring
answered_atstring | null
ended_atstring | null
end_reasonstring | nullagent_hangup, remote_hangup, max_duration, busy, voicemail, no_answer…
livemode obrigatórioboolean

Exemplo

curl
curl "https://api.kanutus.com/v1/calls/call_7Hn2Qd9Wk4Lp6Rt1Xb8Mc3Zf" \
  -H "Authorization: Bearer $KANUTUS_API_KEY"
Testar agora

Roda no seu navegador contra a API de verdade. Use uma chave kt_test_: nada é cobrado. A chave fica só nesta aba.

GET /v1/calls/{id}

Respostas por status

200 Call
200
{
  "id": "string",
  "to": "string",
  "country": "string",
  "purpose": "transactional",
  "status": "queued",
  "ai_disclosure": true,
  "billed_seconds": 0,
  "created_at": "string",
  "answered_at": "string",
  "ended_at": "string",
  "end_reason": "string",
  "livemode": true
}
400 Invalid request
400 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

401 Missing, invalid, expired or revoked credential
401 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

403 Missing permission, blocked or not allowed
403 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

404 Not found
404 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 404,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)
429 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

POST/v1/calls/{id}/hangup

Desligar (idempotente: uma ligação encerrada volta como está) Em breve

Permissão: calls:dial

Em produção responde 501 (em breve). Já dá para testar com uma chave kt_test_ (simulador).

Parâmetros

NomeTipoDescrição
id obrigatóriopath · string

Resposta 200

NomeTipoDescrição
id obrigatóriostring
to obrigatóriostring
country obrigatóriostring
purpose obrigatório"transactional" | "scheduling" | "support" | "marketing"
status obrigatório"queued" | "ringing" | "answered" | "completed" | "busy" | "voicemail" | "no_answer" | "failed" | "blocked"
ai_disclosure obrigatóriotrue
billed_seconds obrigatóriointeger
created_at obrigatóriostring
answered_atstring | null
ended_atstring | null
end_reasonstring | nullagent_hangup, remote_hangup, max_duration, busy, voicemail, no_answer…
livemode obrigatórioboolean

Exemplo

curl
curl -X POST "https://api.kanutus.com/v1/calls/call_7Hn2Qd9Wk4Lp6Rt1Xb8Mc3Zf/hangup" \
  -H "Authorization: Bearer $KANUTUS_API_KEY"
Testar agora

Roda no seu navegador contra a API de verdade. Use uma chave kt_test_: nada é cobrado. A chave fica só nesta aba.

POST /v1/calls/{id}/hangup

Respostas por status

200 The call, ended
200
{
  "id": "string",
  "to": "string",
  "country": "string",
  "purpose": "transactional",
  "status": "queued",
  "ai_disclosure": true,
  "billed_seconds": 0,
  "created_at": "string",
  "answered_at": "string",
  "ended_at": "string",
  "end_reason": "string",
  "livemode": true
}
400 Invalid request
400 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

401 Missing, invalid, expired or revoked credential
401 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

403 Missing permission, blocked or not allowed
403 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

404 Not found
404 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 404,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

409 Conflict (idempotency or state)
409 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 409,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)
429 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

POST/v1/calls/{id}/dtmf

Apertar teclas do telefone (DTMF) em menus como "tecle 2 para vendas": 0-9, * e #, até 32 Em breve

Permissão: calls:dial

Em produção responde 501 (em breve). Já dá para testar com uma chave kt_test_ (simulador).

Parâmetros

NomeTipoDescrição
id obrigatóriopath · string

Corpo da requisição

NomeTipoDescrição
digits obrigatóriostring0-9, * and #; spaces and dashes are ignored · length 1–64

Resposta 200

NomeTipoDescrição
id obrigatóriostring
sent obrigatóriostring
status obrigatório"queued" | "ringing" | "answered" | "completed" | "busy" | "voicemail" | "no_answer" | "failed" | "blocked"
livemode obrigatórioboolean

Exemplo

curl
curl -X POST "https://api.kanutus.com/v1/calls/call_7Hn2Qd9Wk4Lp6Rt1Xb8Mc3Zf/dtmf" \
  -H "Authorization: Bearer $KANUTUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"digits":"2#"}'
Testar agora

Roda no seu navegador contra a API de verdade. Use uma chave kt_test_: nada é cobrado. A chave fica só nesta aba.

POST /v1/calls/{id}/dtmf

Respostas por status

200 Keys sent
200
{
  "id": "string",
  "sent": "string",
  "status": "queued",
  "livemode": true
}
400 Invalid request
400 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 400,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

401 Missing, invalid, expired or revoked credential
401 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 401,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

403 Missing permission, blocked or not allowed
403 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 403,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

404 Not found
404 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 404,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

409 Conflict (idempotency or state)
409 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 409,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro

429 Rate limit exceeded (see RateLimit-* and Retry-After headers)
429 application/problem+json
{
  "type": "https://docs.kanutus.com/errors",
  "title": "<code>",
  "status": 429,
  "code": "<code>",
  "message": "…",
  "request_id": "req_…"
}

Ver todos os códigos de erro