Guias

Fazer chamadas a partir do teu programa

O teu programa pode pedir à Atendia que o assistente virtual ligue a alguém. Por exemplo: «liga a este cliente na véspera e lembra a consulta de 18 de novembro de 2026, às 15h00». A Atendia guarda o pedido, liga quando chega a vez e, no fim, envia o resultado ao teu programa.

O endereço da API é https://api.atendia.pt/api/v1. Cada pedido leva a chave no cabeçalho x-api-key e o corpo em JSON.

Criar a chave

  • Na consola, abre «Definições» → «Chaves API» → «Nova chave API». Dá um nome e escolhe o tipo «Leitura e chamadas».
  • Só o proprietário ou um administrador cria chaves. Para criar uma chave «Leitura e chamadas», precisa também do direito de lançar e cancelar chamadas. O tipo não se muda depois.
  • Copia a chave quando a consola a mostra: só aparece uma vez. Guarda-a como segredo (no Make e no n8n, numa credencial) e nunca a ponhas no código.
  • Uma chave «Só leitura» só consulta. Se pedir ou cancelar uma chamada, recebe 403 com o código API_KEY_CANNOT_CALL. As chaves criadas antes destes dois tipos são «Só leitura».
  • Uma chave não cria nem revoga chaves e não mexe em pagamentos. Uma chave revogada, desativada ou expirada recebe 401 de imediato. Ao revogar uma chave com chamadas por sair, a consola pergunta se as cancela ou se as mantém.
  • Cada chave faz até 60 pedidos por minuto. Acima disso, recebe 429 com o código RATE_LIMITED e o cabeçalho Retry-After, com os segundos a esperar.

O pedido mínimo

O pedido mínimo leva só o agente e o número a quem ligar: POST /outbound-calls com agentId e phoneNumber.

json
{
  "agentId": "00000000-0000-4000-8000-000000000000",
  "phoneNumber": "+351210000000"
}

A Atendia verifica que o agente e o número que liga são da conta da chave e que o destino é permitido. Só responde depois de guardar o pedido.

A resposta é 201, com o identificador da chamada (outboundId) e o estado. Guarda o outboundId: serve para consultar e para cancelar.

json
{
  "success": true,
  "message": "Outbound call requested",
  "data": {
    "outboundId": "11111111-1111-4111-8111-111111111111",
    "status": "SCHEDULED",
    "reason": null,
    "waitReason": null,
    "scheduledAt": "2026-11-17T09:30:00.000Z",
    "reference": null,
    "origin": { "type": "api_key", "name": "Agenda" }
  }
}

Os dados do pedido

  • agentId: o agente que liga. Obrigatório.
  • phoneNumber: o número a quem ligar, com o indicativo, por exemplo +351210000000. Obrigatório.
  • fromNumber: o número da Atendia que liga. Só é preciso se o agente tiver mais do que um número.
  • scheduledAt: a hora a partir da qual ligar, com fuso. Sem ela, liga agora. Ver «A hora «a partir de»».
  • firstMessage: a primeira frase do assistente virtual nesta chamada. Sem ela, vale a do agente.
  • systemPrompt: instruções extra para esta chamada. Juntam-se às instruções do agente e valem só nesta chamada.
  • dynamicVariables: as variáveis da chamada, como na consola, por exemplo {"data_consulta": "18 de novembro de 2026, às 15h00"}. Escreve as datas completas, com o dia, o mês e a hora, nunca «amanhã»: a chamada pode sair mais tarde do que a hora pedida, por exemplo à espera do horário do agente.
  • reference: a tua referência, por exemplo o código da marcação. Ver «A referência».
  • notAfter: não ligar depois desta data e hora, com fuso. Opcional. Ver «Não ligar depois de».

A hora «a partir de»

  • scheduledAt é a hora «a partir de» a qual a chamada pode sair, não a hora exata. A essa hora, a chamada entra na fila do número e sai quando houver uma linha livre.
  • A hora leva sempre o fuso, por exemplo 2026-12-01T10:00:00+00:00. Em Portugal continental, o fuso é +00:00 no inverno e +01:00 no verão. Sem fuso, o pedido é recusado: assim, «10h00» nunca sai às 11h00.
  • Até 5 minutos no passado conta como «agora». Mais antiga, o pedido é recusado (400). Até 90 dias no futuro é aceite; mais longe, é recusado.
  • Espalha as horas. Com 50 lembretes para as 9h00 num número com uma linha, os últimos saem bem depois das 9h00. Põe-nos, por exemplo, de 3 em 3 minutos.

Não ligar depois de

  • notAfter é a data e hora limite do pedido: nenhuma chamada deste pedido começa depois dela. É opcional. Sem ela, a chamada espera sem prazo, como até aqui.
  • Leva sempre o fuso, como scheduledAt. Num lembrete, põe a hora da consulta. Por exemplo, para uma consulta a 18 de novembro de 2026, às 15h00: "scheduledAt": "2026-11-17T15:00:00+00:00" e "notAfter": "2026-11-18T15:00:00+00:00".
  • Um limite que já passou é recusado com 400 e o código NOT_AFTER_IN_PAST. Uma hora marcada igual ou posterior ao limite é recusada com 400 e o código SCHEDULED_AT_AFTER_NOT_AFTER. Em nenhum dos casos é criada uma chamada.
  • Se o limite passar antes de a chamada sair, por exemplo à espera do horário, de linha ou de saldo, a chamada já não sai. Pouco depois do limite, fica «Falhada» (FAILED), com o motivo deadline_passed («Fora do prazo»), e o teu programa recebe o resultado com esse motivo. Entre tentativas é diferente: ver «Nova tentativa».
  • A consulta e o resultado trazem notAfter, com o limite do pedido, ou null se o pedido não o tiver. notAfter existe só no pedido de uma chamada (POST /outbound-calls), não na campanha por lista.

A fila

  • Cada chamada pedida pela API nasce «Agendada» (SCHEDULED). Quando chega a hora, entra na fila do número da Atendia que liga.
  • Sai primeiro a que tem a hora mais antiga; em caso de empate, a que foi pedida primeiro. As chamadas únicas saem antes das chamadas de uma campanha no mesmo número.
  • Uma chamada à espera mostra a razão em waitReason: line («à espera de linha»), credit («à espera de saldo») ou hours («à espera do horário», ver «O horário do agente»). Podem aparecer razões novas: trata uma que não conheces como «à espera». Sem notAfter, não há prazo: espera até sair ou até a cancelares.
  • Sem saldo, a chamada não falha: espera. Se o carregamento automático estiver ligado, é pedido como hoje. A Atendia volta a tentar com intervalos que crescem até 30 minutos, por isso, depois de carregares saldo, a fila pode demorar até 30 minutos a retomar.
  • Um pedido sem hora, ou com a hora já chegada, tenta ligar logo, sem passar à frente de quem já espera. Por isso, a resposta pode demorar até cerca de 2 minutos. Diz o estado desse momento: IN_PROGRESS («Em curso»), SCHEDULED com a razão da espera, ou FAILED com o motivo.
  • Nesse caso, só a falta de saldo (402) recusa o pedido. A chamada fica «Falhada», não há envio de resultado e o identificador de pedido fica livre. Se a conta já estiver à espera de saldo, a chamada junta-se à espera, sem recusa.
  • Põe o tempo limite do teu programa em 3 minutos ou mais. Se desistir antes, repete o pedido com o mesmo Idempotency-Key: recebe o estado do momento, sem segunda chamada.

O horário do agente

  • O agente pode ter um horário das chamadas: os dias da semana e uma hora de início e de fim, iguais em todos os dias marcados. Configura-se na consola, em «Regras de saída», na página do agente. Vem desligado.
  • Com o horário desligado, nada muda: a chamada sai quando chega a vez, a qualquer hora.
  • Com o horário ligado, nenhuma chamada pedida pela API começa fora dele. As horas são as do fuso do agente, e a hora do fim já fica de fora: das 9h00 às 18h00, a última chamada começa antes das 18h00. Os feriados não são excluídos. Uma chamada em curso não é cortada.
  • A hora marcada (scheduledAt) continua a ser «a partir de». Se cair fora do horário, a chamada espera pela abertura seguinte. As chamadas à espera saem pela ordem em que ficaram prontas.
  • Enquanto espera, a chamada fica «Agendada» (SCHEDULED), com waitReason hours («À espera do horário»). nextAttemptAt diz a hora a que sai: a mais tarde entre scheduledAt e a abertura seguinte do horário. A essa hora, entra na fila do número, como as outras.
  • Quando a chamada não espera pelo horário nem por nova tentativa, nextAttemptAt é null.
  • Se o limite notAfter passar enquanto a chamada espera pelo horário, ela não sai: fica «Falhada», com o motivo deadline_passed (entre tentativas, ver «Nova tentativa»).
  • O horário vale também para as campanhas do agente. Não vale na «Chamada rápida» da consola, que liga logo.

Exemplo: uma marcação feita na segunda-feira, 16 de novembro de 2026, às 20h00, para uma consulta a 18 de novembro de 2026, às 15h00. O agente tem o horário de segunda a sexta, das 9h00 às 18h00, na hora de Lisboa. A chamada espera pela abertura de terça-feira às 9h00. Só alguns campos de data:

json
{
  "outboundId": "11111111-1111-4111-8111-111111111111",
  "status": "SCHEDULED",
  "reason": null,
  "waitReason": "hours",
  "nextAttemptAt": "2026-11-17T09:00:00.000Z",
  "scheduledAt": "2026-11-16T20:00:00.000Z",
  "notAfter": "2026-11-18T15:00:00.000Z",
  "reference": "marcacao-4821"
}

A referência

  • reference é o teu identificador, por exemplo marcacao-4821. Volta em cada resposta, na consulta e no resultado.
  • A referência não deve levar dados pessoais: nem nomes, nem números de telefone, nem e-mails. Usa um código do teu sistema.
  • Até 200 caracteres. Os espaços nas pontas são cortados, e uma referência vazia conta como «sem referência». Quebras de linha e caracteres invisíveis são recusados.
  • Para encontrar as chamadas de uma referência, usa GET /outbound-calls?reference=marcacao-4821. A procura é exata e só vê a tua conta.

Pedidos repetidos

  • Envia sempre o cabeçalho Idempotency-Key, com um valor único por chamada, até 200 caracteres. Se a rede falhar e o teu programa repetir o pedido, a Atendia reconhece-o e não liga duas vezes.
  • O mesmo identificador com o mesmo corpo devolve a mesma chamada, com 201 e o estado do momento. Vale enquanto a chamada espera ou está em curso, e mais 24 horas depois de terminar.
  • O mesmo identificador com um corpo diferente, ou usado antes numa campanha, é recusado com 409 e o código IDEMPOTENCY_KEY_REUSED. Nenhuma chamada nova é criada. O identificador vale enquanto a chamada espera ou está em curso, e 24 horas depois de terminar; depois disso, o mesmo identificador cria uma chamada nova.
  • Um pedido recusado na validação não gasta o identificador: corrige o pedido e reenvia com o mesmo.
  • Sem hora marcada, repetir funciona sempre dentro desse prazo, porque o corpo é o mesmo. Com hora marcada, repetir mais de 5 minutos depois dessa hora é recusado (400), porque a hora já passou. Nesse caso, procura primeiro a chamada pela referência. Se não existir, envia o pedido com uma hora «a partir de» nova e um identificador novo.
  • Sem o cabeçalho, cada envio conta como um pedido novo.

O resultado

  • No fim, a Atendia envia o resultado para o «Webhook pós-chamada» do agente (separador «E-mail e webhooks»), como nas outras chamadas. Sem esse endereço, não há envio: o teu programa consulta a chamada.
  • O corpo leva os campos de sempre (callId, agentId, startedAt, endedAt, durationSeconds, direction, callerId, extractedData) e ainda status, reason, outboundId, campaignId, origin, reference, notAfter, callbackScheduled e callbackOf (ver «A chamada de volta»), answeredBy e messageLeft (ver «A caixa de correio»), attempt, maxAttempts, nextAttemptAt e endedByDeadline (ver «Nova tentativa»). A transcrição e o endereço da gravação vêm também, se o webhook do agente os pedir.
  • Sai em todos os estados finais: COMPLETED (atendida), NOT_ANSWERED («Sem resposta») e FAILED («Falhada» ou «Cancelada»). Sai em todas as chamadas de saída, também nas lançadas na consola, exceto os contactos recusados ao importar uma campanha da consola.
  • Uma chamada que termina sem chegar a ligar, por exemplo cancelada na fila, envia o resultado cerca de 2 minutos depois, com callId, startedAt e endedAt a null.
  • O mesmo resultado pode chegar duas vezes. Acontece quando a Atendia repete um envio que a tua API não confirmou, ou quando o registo da chamada chega depois de um resultado já enviado. Guarda o que já trataste e ignora o repetido. Se chegarem dois estados diferentes para a mesma chamada, vale o último.
  • Atenção: cancelar muitas chamadas dá muitos envios. Cada chamada cancelada envia o seu resultado; ao cancelar uma campanha, conta com um envio por contacto que ainda não tinha saído.
  • Um pedido para agora recusado na própria resposta (sem saldo ou sem minutos do plano) não envia resultado: o teu programa já recebeu a recusa.
  • Responde 2xx depressa. Se o envio falhar, o resultado continua disponível na consulta da chamada.

Exemplo do resultado de uma chamada cancelada na fila:

json
{
  "callId": null,
  "agentId": "00000000-0000-4000-8000-000000000000",
  "startedAt": null,
  "endedAt": null,
  "durationSeconds": null,
  "direction": "outbound",
  "callerId": "+351210000000",
  "extractedData": [],
  "status": "FAILED",
  "reason": "cancelled",
  "outboundId": "11111111-1111-4111-8111-111111111111",
  "campaignId": null,
  "origin": { "type": "api_key", "name": "Agenda" },
  "reference": "marcacao-4821",
  "notAfter": null
}

A chamada de volta («Ligue-me mais tarde»)

  • O agente pode ter a opção «Ligue-me mais tarde». Configura-se na consola, em «Regras de saída», na página do agente. Vem desligada. Ligada, quando a pessoa atende e pede para lhe ligarem depois, o agente combina o dia e a hora e, com a confirmação da pessoa, a Atendia marca uma chamada de volta. Vale em todas as chamadas de saída do agente, também nas lançadas na consola.
  • Quem decide é a Atendia, não o agente. A chamada de volta liga para o mesmo número, com o mesmo agente, o mesmo número de origem, as mesmas variáveis, as mesmas instruções extra e a mesma reference. O teu programa não a pede nem lhe muda os dados.
  • A hora tem de estar no futuro, até 30 dias, dentro do horário do agente, se estiver ligado, e antes do notAfter do pedido, se houver. Há no máximo uma chamada de volta por chamada e duas por pedido: o pedido é a chamada original mais as chamadas de volta que nasceram dela.
  • A chamada original termina como atendida (COMPLETED). A consulta e o resultado dela trazem callbackScheduled, com at, a hora a partir da qual a chamada de volta sai, e outboundId, o identificador da chamada de volta. Assim sabes que o pedido ainda não fechou. Sem chamada de volta, callbackScheduled é null.
  • A chamada de volta é uma chamada nova: fica «Agendada» (SCHEDULED) até à hora combinada e depois segue a fila, o horário do agente e o saldo, como as outras. Gasta saldo como as outras. No fim, envia o seu próprio resultado, com a mesma reference e com callbackOf, o outboundId da chamada original. Nas outras chamadas, callbackOf é null.
  • Para ver todas as chamadas de um pedido, procura pela referência (GET /outbound-calls?reference=...). Uma chamada de volta cancela-se sempre pelo seu outboundId, com as regras de uma chamada avulsa. Vale também quando nasceu de um contacto de uma campanha: o contacto não se cancela assim, mas a chamada de volta sim. Cancelar a campanha também a cancela.
  • Se cancelares uma chamada com a conversa em curso, o cancelamento continua a ser recusado com 400 e details.status, e vem também details.furtherAttempts: false: a conversa acaba normalmente, mas já não fica marcada uma chamada de volta.
  • Ao revogar uma chave, as chamadas de volta marcadas contam como chamadas por sair: cancelam-se com as outras ou mantêm-se. Se se mantiverem, a consola diz até quando ainda podem sair.

Exemplo: numa chamada pedida a 16 de novembro de 2026, a pessoa pediu para lhe ligarem a 18 de novembro de 2026, às 15h00, na hora de Lisboa. Alguns campos do resultado da chamada original:

json
{
  "status": "COMPLETED",
  "outboundId": "11111111-1111-4111-8111-111111111111",
  "callerId": "+351210000000",
  "reference": "marcacao-4830",
  "callbackScheduled": {
    "at": "2026-11-18T15:00:00.000Z",
    "outboundId": "22222222-2222-4222-8222-222222222222"
  },
  "callbackOf": null
}

E alguns campos do resultado da chamada de volta, depois de atendida:

json
{
  "status": "COMPLETED",
  "outboundId": "22222222-2222-4222-8222-222222222222",
  "callerId": "+351210000000",
  "reference": "marcacao-4830",
  "callbackScheduled": null,
  "callbackOf": "11111111-1111-4111-8111-111111111111"
}

A caixa de correio

  • O agente reconhece quando atende uma caixa de correio ou outra gravação, e não conversa com ela. O que faz a seguir escolhe-se na consola, em «Regras de saída», na página do agente: «Terminar a chamada, sem mensagem» (o que vem escolhido) ou «Deixar uma mensagem». Vale em todas as chamadas de saída do agente, também nas lançadas na consola.
  • A mensagem é um texto teu, até 500 caracteres, que pode usar as variáveis da chamada (dynamicVariables). O agente espera que a gravação acabe, diz o texto uma vez, tal como está, na voz do agente, e termina a chamada. Se a voz do agente não ficar pronta a tempo, uma voz de reserva diz o texto exato, e a mensagem fica deixada. Um texto sem variáveis fica gravado na voz do agente na primeira caixa de correio e serve para as seguintes. Escreve as datas completas nas variáveis, por exemplo «18 de novembro de 2026, às 15h00», nunca «amanhã».
  • Não fica mensagem quando falta uma variável ou ela vem vazia e o agente não tem um valor para quando falta, quando o texto preenchido passa de 1000 caracteres, quando a gravação não acaba a tempo, ou quando a gravação não aceita mensagens (por exemplo, «o número não está atribuído»). Quando falta uma variável, o histórico da consola diz qual.
  • A mensagem fica gravada num telefone que outras pessoas podem ouvir. Não ponhas nela, nem nas variáveis que ela usa, o motivo da consulta nem outros dados de saúde.
  • Uma chamada atendida pela caixa de correio ou por outra gravação termina «Sem resposta» (NOT_ANSWERED), como quando ninguém atende, e gasta os segundos que durou, porque a ligação foi atendida. O mesmo vale para uma chamada atendida em que ninguém fala até ao fim. Na dúvida, o agente trata quem atendeu como uma pessoa.
  • A consulta e o resultado trazem answeredBy, quem atendeu: person (uma pessoa), voicemail (a caixa de correio), operator_recording (uma gravação do operador, como «o telemóvel está desligado», ou um menu, quando o agente não navega em menus) ou nobody_spoke (atendeu, mas ninguém falou até ao fim).
  • answeredBy só vem quando o reconhecimento correu, ou com nobody_spoke, que vem sempre. Noutros casos, por exemplo quando ninguém atende ou quando a Atendia suspende o reconhecimento, vem null ou não vem: trata os dois da mesma forma.
  • messageLeft diz se ficou mensagem: true só quando o agente a disse. Trata qualquer outro valor como «sem mensagem». Com «Terminar a chamada, sem mensagem», nunca é true.

Exemplo: num lembrete da marcação de 18 de novembro de 2026, às 15h00, atendeu a caixa de correio e o agente deixou a mensagem. Alguns campos do resultado:

json
{
  "status": "NOT_ANSWERED",
  "outboundId": "33333333-3333-4333-8333-333333333333",
  "callerId": "+351210000000",
  "durationSeconds": 31,
  "reference": "marcacao-4835",
  "answeredBy": "voicemail",
  "messageLeft": true
}

Nova tentativa

  • O agente pode voltar a ligar sozinho quando a chamada não chega a uma pessoa. Liga-se na consola, em «Regras de saída», na página do agente, no bloco «Nova tentativa». Vem desligada. Escolhes quantas vezes volta a ligar, de 1 a 5 (2 ao ligar a opção), e o intervalo: 5, 15 ou 30 minutos, 1, 2, 4, 8 ou 24 horas (1 hora ao ligar a opção).
  • Volta a ligar quando ninguém atendeu, o número estava ocupado ou rejeitou, atendeu a caixa de correio e não ficou mensagem, atendeu outra gravação, ou atenderam e ninguém falou. Não volta a ligar quando a pessoa atendeu, quando ficou mensagem, quando a chamada falhou (FAILED) ou quando foi cancelada.
  • Vale nas chamadas pedidas pela API, nas campanhas por lista, nas campanhas da consola e nas chamadas de volta. Não vale na «Chamada rápida» da consola.
  • O intervalo conta a partir do fim da tentativa anterior. Cada tentativa espera pelo horário do agente, por uma linha e pelo saldo, como qualquer chamada.
  • Para o teu programa, é sempre a mesma chamada: o mesmo outboundId, a mesma reference e um só resultado, enviado depois da última tentativa. Entre tentativas, a chamada fica «Agendada» (SCHEDULED), com waitReason retry («Nova tentativa»), e nextAttemptAt diz a hora da tentativa seguinte. Se essa hora calhar fora do horário do agente, vem waitReason hours, com a hora da abertura.
  • A consulta e o resultado trazem attempt, a tentativa em que a chamada vai: 1 na primeira chamada; à espera da segunda, já é 2. No resultado, é a tentativa em que acabou. maxAttempts é o máximo de chamadas do pedido: 1 mais as novas tentativas do agente, e nunca menos do que as já feitas. Sem nova tentativa, os dois são 1.
  • Com notAfter, nenhuma tentativa começa depois do limite. Se o limite passar entre tentativas, a chamada acaba com o estado da última tentativa, «Sem resposta» (NOT_ANSWERED), sem motivo em reason, e com endedByDeadline a true. Em todos os outros casos, endedByDeadline é false.
  • Cancelar a chamada entre tentativas cancela as que faltam. Desligar a opção no agente não cancela as tentativas já marcadas: se não as quiseres, cancela a chamada. «Revogar e cancelar» uma chave cancela também as tentativas que faltam; «Revogar e manter» deixa-as sair.
  • Cada nova tentativa é uma chamada. Uma chamada que ninguém atende não gasta saldo. Uma gravação que atende e uma chamada atendida em silêncio gastam os segundos que duraram.

Exemplo: um lembrete da consulta de 18 de novembro de 2026, às 15h00. O agente volta a ligar 2 vezes, de hora a hora. Ninguém atendeu a primeira chamada, que acabou a 17 de novembro às 10h00, na hora de Lisboa. A consulta mostra a chamada à espera da segunda:

json
{
  "outboundId": "44444444-4444-4444-8444-444444444444",
  "status": "SCHEDULED",
  "waitReason": "retry",
  "nextAttemptAt": "2026-11-17T11:00:00.000Z",
  "attempt": 2,
  "maxAttempts": 3,
  "endedByDeadline": false,
  "notAfter": "2026-11-18T15:00:00.000Z",
  "reference": "marcacao-4840"
}

Configurar a assinatura

  • Para saberes que o resultado vem da Atendia, cria o segredo de assinatura da organização, que começa por whsec_, na consola, em «Definições» → «Assinatura dos pedidos». As chaves API não o podem criar. Com ele, cada envio leva webhook-id, webhook-timestamp e webhook-signature.
  • Com registo da chamada, o webhook-id é atd_postcall_, o id do agente, _ e o callId. Sem registo da chamada, é atd_postcall_, o id do agente, _, o outboundId, _ e o estado em minúsculas, por exemplo _failed. Uma repetição do mesmo envio leva o mesmo webhook-id. O resultado que chega com o registo da chamada, depois de um enviado sem registo, leva outro id: reconhece-o pelo par outboundId e status.
  • Sem assinatura, reconhece um envio repetido pelo par outboundId e status.

Como verificar a assinatura, com exemplos: página das ferramentas HTTP, «Assinatura dos pedidos».

Consultar uma chamada

  • GET /outbound-calls/{outboundId} devolve a chamada num só pedido: status, reason, waitReason, nextAttemptAt, scheduledAt, notAfter, callbackScheduled, callbackOf, answeredBy, messageLeft, attempt, maxAttempts, endedByDeadline, reference, origin, durationSeconds e os dados recolhidos (extractedData).
  • Uma chamada à espera mostra a hora e a razão da espera. À espera do horário ou de nova tentativa, mostra também a hora a que sai, em nextAttemptAt. Uma chamada cancelada é FAILED com o motivo cancelled.
  • Se o agente não guarda dados pessoais, noDataKept é true e os dados recolhidos vêm vazios. Pouco depois de a chamada terminar e de o resultado sair, a Atendia apaga também o número, a primeira frase, as instruções e as variáveis. A reference fica.
  • Uma chamada de outra conta responde como se não existisse (404), e a procura por uma referência de outra conta devolve uma lista vazia.

Os estados

  • SCHEDULED: «Agendada», à espera da hora, à espera do horário do agente, na fila ou à espera de nova tentativa.
  • IN_PROGRESS: «Em curso».
  • COMPLETED: atendida e terminada.
  • NOT_ANSWERED: «Sem resposta». Também quando atendeu a caixa de correio ou outra gravação, ou quando ninguém falou (ver «A caixa de correio»). Se o agente tiver a nova tentativa ligada, a Atendia volta a ligar sozinha, e este estado só chega depois da última tentativa (ver «Nova tentativa»). Sem ela, é o teu programa que decide pedir outra chamada.
  • FAILED: «Falhada», com o motivo em reason. Uma chamada cancelada é FAILED com reason cancelled.

Cancelar

  • POST /outbound-calls/{outboundId}/cancel cancela uma chamada «Agendada», com hora marcada ou na fila. A resposta é a chamada, FAILED com o motivo cancelled, e o teu programa recebe o resultado com esse motivo.
  • Cancelar de novo uma chamada já cancelada devolve a mesma resposta, sem novo envio.
  • Se a chamada já começou a marcar, ou já terminou, o cancelamento é recusado com 400, e details.status diz o estado atual. Com a conversa em curso, vem também details.furtherAttempts: false (ver «A chamada de volta»).
  • Uma chave só cancela chamadas únicas pedidas por chaves; as de uma campanha cancelam-se com a campanha. As lançadas na consola cancelam-se na consola; para a chave, respondem 404.
  • Se só tiveres a referência, procura primeiro as chamadas com GET /outbound-calls?reference=... e cancela cada uma pelo outboundId.
  • Uma campanha pedida por chave cancela-se com POST /outbound-calls/batches/{campaignId}/cancel. As chamadas já em curso terminam normalmente.

Campanha por lista

  • POST /outbound-calls/batches/list cria uma campanha com a lista no próprio pedido: name, agentId, fromNumber (se o agente tiver mais do que um número), scheduledAt (opcional, com as regras da hora) e contacts.
  • Cada contacto leva phoneNumber e, se quiseres, firstMessage, systemPrompt, dynamicVariables e reference. Numa campanha, as instruções de um contacto substituem as do agente nessa chamada. Os nomes das variáveis seguem as regras das colunas do ficheiro: minúsculas e sem espaços.
  • Até 5 000 contactos e 2 MB por pedido. Acima de 2 MB, a resposta é 413 com o código REQUEST_TOO_LARGE. Envia listas maiores por ficheiro.
  • A resposta diz quantos contactos foram aceites (accepted) e quantos não (rejectedCount), e lista os primeiros 100 recusados, com a posição, a referência e o motivo. Os outros seguem.
  • A campanha aparece em «Campanhas» na consola. Cada chamada envia o seu resultado, com a referência do contacto. O cabeçalho Idempotency-Key funciona como num pedido de chamada.

Códigos de recusa

Cada recusa traz o corpo de erro de sempre: success: false, code, message (em inglês), details, fieldErrors e requestId. Decide pelo estado HTTP e pelo code, nunca pela mensagem.

CódigoHTTPO que quer dizerO que fazer
API_KEY_CANNOT_CALL403A chave é «Só leitura».Cria uma chave «Leitura e chamadas» na consola e usa-a.
IDEMPOTENCY_KEY_REUSED409O identificador de pedido já foi usado com outro corpo, ou numa campanha.Usa um identificador novo para um pedido novo. Para saber o que aconteceu ao primeiro, procura-o pela referência.
RATE_LIMITED429Mais de 60 pedidos por minuto com esta chave.Espera os segundos de Retry-After e repete.
DESTINATION_RULE_MISSING400O operador do número que liga não tem regra de destinos, por isso as chamadas pedidas por chave não saem por esse número.Usa outro número da Atendia em fromNumber, ou fala connosco.
OUTBOUND_API_PAUSED503A Atendia parou as chamadas pedidas por chave, numa emergência. Consultar e cancelar continuam a funcionar.Repete mais tarde. As chamadas já aceites esperam e saem quando a pausa acabar.
REQUEST_TOO_LARGE413A lista da campanha passa os 2 MB.Divide a lista, ou envia-a por ficheiro.
VALIDATION_ERROR400Um campo ou o cabeçalho Idempotency-Key estão errados, ou a hora está mais de 5 minutos no passado ou a mais de 90 dias. fieldErrors diz o campo.Corrige o pedido e reenvia, com o mesmo identificador.
UNAUTHORIZED401Falta a chave, ou está revogada, desativada ou expirada.Confirma o cabeçalho x-api-key, ou cria uma chave nova.
FORBIDDEN403O pedido não vem de uma chave, ou a rota não está aberta a chaves, como a «Chamada rápida» da consola.Pede chamadas com POST /outbound-calls e uma chave.
NOT_FOUND404O agente, o número, a chamada ou a campanha não existem nesta conta, ou não foram pedidos por uma chave.Confirma os identificadores.
INSUFFICIENT_CREDIT402Uma chamada para agora, sem saldo. Fica «Falhada» com o motivo insufficient_credit.Carrega saldo e repete o pedido. Podes usar o mesmo identificador.
DIDLOGIC_OUTBOUND_BLOCKED400O operador do número não liga para este destino. details.reason é destination_not_allowed.Confirma o número de destino.
BAD_REQUEST400Outra recusa, explicada na mensagem e, quando existe, em details.reason. Por exemplo: do_not_call (o número está na lista «Não ligar» da tua conta, e nada é criado), falta o fromNumber, ou o agente não está ativo.Lê details.reason e a mensagem, e corrige o pedido.
INTERNAL_SERVER_ERROR503Com 503, a Atendia não conseguiu guardar o pedido e nada foi criado. Com 500, a chamada pode já existir.Repete o mesmo pedido, com o mesmo identificador: recebes a chamada, se já existir.
PAYLOAD_TOO_LARGE413O corpo de um pedido de chamada passa os 100 kB.Encurta os textos do pedido.
NOT_AFTER_IN_PAST400O limite notAfter já passou quando o pedido chegou.Confirma a data e o fuso de notAfter. Se a consulta já passou, não há chamada a pedir.
SCHEDULED_AT_AFTER_NOT_AFTER400A hora marcada (scheduledAt) é igual ou posterior ao limite (notAfter): a chamada nunca podia sair.Marca uma hora antes do limite, ou confirma as datas e os fusos.

Motivos de uma chamada falhada

Uma chamada FAILED traz o motivo em reason, de uma lista fechada. A consola mostra o mesmo motivo, em texto. Podem aparecer motivos novos: trata um motivo que não conheces como uma falha.

MotivoNa consolaQuando
cancelledCanceladaCancelaste a chamada, pela chave ou na consola.
campaign_cancelledCampanha canceladaA campanha foi cancelada antes de esta chamada sair.
dial_failedA chamada não ligouA chamada não chegou a ligar (recusa do operador ou falha do lado da Atendia).
dial_outcome_uncertainSem confirmação de que ligouNão se sabe se a marcação chegou ao operador. A Atendia não volta a marcar: decide tu se pedes outra chamada.
agent_unavailableAgente indisponívelO agente foi apagado ou desativado, ou parou durante a chamada.
source_number_unavailableNúmero de origem indisponívelO número da Atendia que liga deixou de estar ativo, ou mudou de conta.
destination_not_allowedDestino não permitidoO operador do número não liga para este destino.
destination_rule_missingOperador sem regra de destinosO operador do número não tem regra de destinos.
plan_minutes_exhaustedMinutos do plano esgotadosJá não é usado. Aparece só em chamadas antigas, de quando havia minutos do plano.
insufficient_creditSaldo insuficienteUm pedido para agora, sem saldo, recusado na própria resposta.
dispatch_interruptedEnvio interrompidoA saída foi interrompida várias vezes do lado da Atendia.
import_rejectedRecusado na importaçãoNuma campanha, o contacto foi recusado ao ler a lista.
deadline_passedFora do prazoO limite «não ligar depois de» do pedido passou antes de a chamada sair.
do_not_callEstá na lista «Não ligar»O número está na lista «Não ligar» da tua conta. A chamada não se faz e não há nova tentativa. Numa campanha, o contacto é recusado logo ao ler a lista.
import_failedA lista da campanha não foi importadaNuma campanha, a leitura da lista falhou de vez. A campanha fica «Falhada» e as chamadas que faltavam já não se fazem.

O que a lei pede

Nota sobre a lei: chamadas a consumidores entre as 9h e as 22h, identificar-se logo e ter consentimento prévio para chamadas de marketing. A Atendia não trava nada disto; a escolha é tua. Por exemplo, começa a primeira frase do assistente virtual pelo nome da tua empresa.

Exemplos

Make

  • No cenário, junta o módulo «HTTP» → «Make a request». URL: https://api.atendia.pt/api/v1/outbound-calls. Método: POST.
  • Cabeçalhos: x-api-key com a tua chave e Idempotency-Key com um valor único da chamada, por exemplo o id da marcação seguido de -lembrete. Não partilhes o cenário com a chave lá dentro.
  • Corpo: «Body type» Raw, «Content type» JSON (application/json), e o JSON do pedido, com os valores do módulo anterior.
  • Liga «Parse response» para ler o outboundId e o status nos módulos seguintes. Sobe o tempo limite do módulo, porque um pedido para agora pode demorar até cerca de 2 minutos.
  • Para receber o resultado, cria outro cenário que começa com «Custom webhook» e põe o seu endereço no «Webhook pós-chamada» do agente. Usa o outboundId ou a reference para encontrar a marcação.

n8n

  • Junta o nó «HTTP Request». Método POST, URL https://api.atendia.pt/api/v1/outbound-calls.
  • Autenticação: «Generic Credential Type» → «Header Auth», com o nome x-api-key e a tua chave como valor. Assim, a chave fica guardada numa credencial.
  • Liga «Send Headers» e junta Idempotency-Key, com uma expressão que dê um valor único por chamada, por exemplo a partir do id da marcação.
  • Liga «Send Body», com «Body Content Type» JSON, e preenche o pedido. Em «Options», sobe o «Timeout» para 180 000 ms.
  • Para receber o resultado, cria outro fluxo com o nó «Webhook», publica-o e põe o endereço de produção no «Webhook pós-chamada» do agente.

Código

Os exemplos leem a chave da variável de ambiente ATENDIA_API_KEY. Os identificadores e o número são de exemplo.

curl: pedir uma chamada

bash
# Placeholder: put the key the console showed you here, never in a file you share.
export ATENDIA_API_KEY="atd_xxxxxxxxxxxxxxxxxxxxxxxx"

curl -X POST https://api.atendia.pt/api/v1/outbound-calls \
  -H "x-api-key: $ATENDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: marcacao-4821-lembrete" \
  -d '{
    "agentId": "00000000-0000-4000-8000-000000000000",
    "phoneNumber": "+351210000000",
    "scheduledAt": "2026-11-17T15:00:00+00:00",
    "notAfter": "2026-11-18T15:00:00+00:00",
    "dynamicVariables": { "data_consulta": "18 de novembro de 2026, às 15h00" },
    "reference": "marcacao-4821"
  }'

Node: pedir uma chamada

javascript
// Node 18 or later. The key comes from the environment, never from the code.
const response = await fetch("https://api.atendia.pt/api/v1/outbound-calls", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ATENDIA_API_KEY,
    "Content-Type": "application/json",
    // One value per call: a repeated request never calls twice.
    "Idempotency-Key": "marcacao-4821-lembrete",
  },
  body: JSON.stringify({
    agentId: "00000000-0000-4000-8000-000000000000",
    phoneNumber: "+351210000000",
    scheduledAt: "2026-11-17T15:00:00+00:00",
    // Never call after the appointment itself.
    notAfter: "2026-11-18T15:00:00+00:00",
    dynamicVariables: { data_consulta: "18 de novembro de 2026, às 15h00" },
    reference: "marcacao-4821",
  }),
  // A call due now can take up to about 2 minutes to answer.
  signal: AbortSignal.timeout(180_000),
});
const answer = await response.json();
if (!response.ok) {
  // Decide by the HTTP status and the code, never by the message.
  throw new Error(`${response.status} ${answer.code}`);
}
console.log(answer.data.outboundId, answer.data.status);

curl: procurar pela referência

bash
curl "https://api.atendia.pt/api/v1/outbound-calls?reference=marcacao-4821" \
  -H "x-api-key: $ATENDIA_API_KEY"

curl: cancelar uma chamada

bash
curl -X POST https://api.atendia.pt/api/v1/outbound-calls/11111111-1111-4111-8111-111111111111/cancel \
  -H "x-api-key: $ATENDIA_API_KEY"