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
403com o códigoAPI_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
401de 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
429com o códigoRATE_LIMITEDe o cabeçalhoRetry-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.
{
"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.
{
"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:00no inverno e+01:00no 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
400e o códigoNOT_AFTER_IN_PAST. Uma hora marcada igual ou posterior ao limite é recusada com400e o códigoSCHEDULED_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 motivodeadline_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, ounullse o pedido não o tiver.notAfterexiste 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») ouhours(«à espera do horário», ver «O horário do agente»). Podem aparecer razões novas: trata uma que não conheces como «à espera». SemnotAfter, 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»),SCHEDULEDcom a razão da espera, ouFAILEDcom 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), comwaitReasonhours(«À espera do horário»).nextAttemptAtdiz a hora a que sai: a mais tarde entrescheduledAte 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
notAfterpassar enquanto a chamada espera pelo horário, ela não sai: fica «Falhada», com o motivodeadline_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:
{
"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 exemplomarcacao-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
201e 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
409e o códigoIDEMPOTENCY_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 aindastatus,reason,outboundId,campaignId,origin,reference,notAfter,callbackScheduledecallbackOf(ver «A chamada de volta»),answeredByemessageLeft(ver «A caixa de correio»),attempt,maxAttempts,nextAttemptAteendedByDeadline(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») eFAILED(«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,startedAteendedAtanull. - 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
2xxdepressa. Se o envio falhar, o resultado continua disponível na consulta da chamada.
Exemplo do resultado de uma chamada cancelada na fila:
{
"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
notAfterdo 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 trazemcallbackScheduled, comat, a hora a partir da qual a chamada de volta sai, eoutboundId, 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 mesmareferencee comcallbackOf, ooutboundIdda 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 seuoutboundId, 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
400edetails.status, e vem tambémdetails.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:
{
"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:
{
"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) ounobody_spoke(atendeu, mas ninguém falou até ao fim). answeredBysó vem quando o reconhecimento correu, ou comnobody_spoke, que vem sempre. Noutros casos, por exemplo quando ninguém atende ou quando a Atendia suspende o reconhecimento, vemnullou não vem: trata os dois da mesma forma.messageLeftdiz se ficou mensagem:truesó 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:
{
"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 mesmareferencee um só resultado, enviado depois da última tentativa. Entre tentativas, a chamada fica «Agendada» (SCHEDULED), comwaitReasonretry(«Nova tentativa»), enextAttemptAtdiz a hora da tentativa seguinte. Se essa hora calhar fora do horário do agente, vemwaitReasonhours, com a hora da abertura. - A consulta e o resultado trazem
attempt, a tentativa em que a chamada vai:1na 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ão1. - 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 emreason, e comendedByDeadlineatrue. 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:
{
"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 levawebhook-id,webhook-timestampewebhook-signature. - Com registo da chamada, o
webhook-idéatd_postcall_, o id do agente,_e ocallId. Sem registo da chamada, éatd_postcall_, o id do agente,_, ooutboundId,_e o estado em minúsculas, por exemplo_failed. Uma repetição do mesmo envio leva o mesmowebhook-id. O resultado que chega com o registo da chamada, depois de um enviado sem registo, leva outro id: reconhece-o pelo paroutboundIdestatus. - Sem assinatura, reconhece um envio repetido pelo par
outboundIdestatus.
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,durationSecondse 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 éFAILEDcom o motivocancelled. - Se o agente não guarda dados pessoais,
noDataKeptétruee 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. Areferencefica. - 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 emreason. Uma chamada cancelada éFAILEDcomreasoncancelled.
Cancelar
POST /outbound-calls/{outboundId}/cancelcancela uma chamada «Agendada», com hora marcada ou na fila. A resposta é a chamada,FAILEDcom o motivocancelled, 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, edetails.statusdiz o estado atual. Com a conversa em curso, vem tambémdetails.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 pelooutboundId. - 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/listcria 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) econtacts.- Cada contacto leva
phoneNumbere, se quiseres,firstMessage,systemPrompt,dynamicVariablesereference. 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 é
413com o códigoREQUEST_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-Keyfunciona 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ódigo | HTTP | O que quer dizer | O que fazer |
|---|---|---|---|
API_KEY_CANNOT_CALL | 403 | A chave é «Só leitura». | Cria uma chave «Leitura e chamadas» na consola e usa-a. |
IDEMPOTENCY_KEY_REUSED | 409 | O 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_LIMITED | 429 | Mais de 60 pedidos por minuto com esta chave. | Espera os segundos de Retry-After e repete. |
DESTINATION_RULE_MISSING | 400 | O 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_PAUSED | 503 | A 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_LARGE | 413 | A lista da campanha passa os 2 MB. | Divide a lista, ou envia-a por ficheiro. |
VALIDATION_ERROR | 400 | Um 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. |
UNAUTHORIZED | 401 | Falta a chave, ou está revogada, desativada ou expirada. | Confirma o cabeçalho x-api-key, ou cria uma chave nova. |
FORBIDDEN | 403 | O 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_FOUND | 404 | O 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_CREDIT | 402 | Uma 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_BLOCKED | 400 | O operador do número não liga para este destino. details.reason é destination_not_allowed. | Confirma o número de destino. |
BAD_REQUEST | 400 | Outra 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_ERROR | 503 | Com 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_LARGE | 413 | O corpo de um pedido de chamada passa os 100 kB. | Encurta os textos do pedido. |
NOT_AFTER_IN_PAST | 400 | O 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_AFTER | 400 | A 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.
| Motivo | Na consola | Quando |
|---|---|---|
cancelled | Cancelada | Cancelaste a chamada, pela chave ou na consola. |
campaign_cancelled | Campanha cancelada | A campanha foi cancelada antes de esta chamada sair. |
dial_failed | A chamada não ligou | A chamada não chegou a ligar (recusa do operador ou falha do lado da Atendia). |
dial_outcome_uncertain | Sem confirmação de que ligou | Não se sabe se a marcação chegou ao operador. A Atendia não volta a marcar: decide tu se pedes outra chamada. |
agent_unavailable | Agente indisponível | O agente foi apagado ou desativado, ou parou durante a chamada. |
source_number_unavailable | Número de origem indisponível | O número da Atendia que liga deixou de estar ativo, ou mudou de conta. |
destination_not_allowed | Destino não permitido | O operador do número não liga para este destino. |
destination_rule_missing | Operador sem regra de destinos | O operador do número não tem regra de destinos. |
plan_minutes_exhausted | Minutos do plano esgotados | Já não é usado. Aparece só em chamadas antigas, de quando havia minutos do plano. |
insufficient_credit | Saldo insuficiente | Um pedido para agora, sem saldo, recusado na própria resposta. |
dispatch_interrupted | Envio interrompido | A saída foi interrompida várias vezes do lado da Atendia. |
import_rejected | Recusado na importação | Numa campanha, o contacto foi recusado ao ler a lista. |
deadline_passed | Fora do prazo | O limite «não ligar depois de» do pedido passou antes de a chamada sair. |
do_not_call | Está 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_failed | A lista da campanha não foi importada | Numa 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-keycom a tua chave eIdempotency-Keycom 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
outboundIde ostatusnos 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
outboundIdou areferencepara encontrar a marcação.
n8n
- Junta o nó «HTTP Request». Método
POST, URLhttps://api.atendia.pt/api/v1/outbound-calls. - Autenticação: «Generic Credential Type» → «Header Auth», com o nome
x-api-keye 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
# 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
// 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
curl "https://api.atendia.pt/api/v1/outbound-calls?reference=marcacao-4821" \
-H "x-api-key: $ATENDIA_API_KEY"curl: cancelar uma chamada
curl -X POST https://api.atendia.pt/api/v1/outbound-calls/11111111-1111-4111-8111-111111111111/cancel \
-H "x-api-key: $ATENDIA_API_KEY"