Upfirst

Conectando

Não há nada para instalar. Aponte seu cliente para https://mcp.upfirst.ai e ele o guiará pelo login no Upfirst na primeira conexão. A autorização é um login padrão OAuth 2.1, então não há chaves de API para copiar ou armazenar.

O servidor roda sobre HTTP transmissível e dá ao seu assistente 25 ferramentas, que podem tanto ler sua conta quanto alterá-la. Escolha seu cliente abaixo.

O Upfirst está no diretório de conectores do Claude. Abra claude.ai/directory/upfirst, adicione o Upfirst, faça login no Upfirst e aprove o acesso. Funciona no aplicativo de desktop do Claude e em claude.ai.

Adicione-o como um conector personalizado

1. Abra Personalizar e depois Conectores.
2. Clique em + e depois em Adicionar conector personalizado.
3. Nomeie-o como Upfirst e cole a URL abaixo como URL do servidor MCP remoto.
4. Deixe os campos avançados de ID do cliente e Segredo do cliente vazios.
5. Clique em Adicionar e depois em Conectar, faça login no Upfirst e aprove o acesso.

https://mcp.upfirst.ai

Nos planos Team e Enterprise, um proprietário adiciona o conector uma vez nas configurações da organização, e todos os outros apenas clicam em Conectar.

Independentemente de como você se conecta, a primeira chamada abre a página de login do Upfirst. Você aprova o acesso uma vez, e a conexão permanece vinculada à sua organização a partir de então.

Convenções

Algumas regras valem para todas as ferramentas. Cada uma carrega uma etiqueta sobre o que faz com seus dados:

• Leitura Busca dados; nunca altera nada.
• Gravação Cria ou atualiza um registro.
• Exclusão Remove permanentemente um registro. Não há desfazer.

IDs vêm das ferramentas de listagem

Os IDs de agentes vêm de list_agents, os de habilidades de list_agent_skills, os de conhecimentos de get_agent_knowledge, os de saudações de list_agent_greetings, os de ações personalizadas de list_custom_actions e os de chamadas de list_calls. Os IDs são sequências de dígitos. As ferramentas de habilidades recebem o ID como skillId; as de conhecimento, saudação e ação personalizada o recebem como id. As ferramentas de atualização e exclusão precisam apenas desse ID. Elas não recebem um agentId.

Registros são vinculados a agentes

Toda habilidade, entrada de conhecimento e ação personalizada está vinculada a um ou mais agentes. As ferramentas de criação recebem agentIds, uma lista com pelo menos um ID de agente. Defina autoLinkNewAgents como true para também dar o registro a todos os agentes que você criar depois. Nesse caso, agentIds deve listar todos os agentes atuais. As ferramentas de atualização alteram os vínculos somente quando você envia tanto agentIds quanto autoLinkNewAgents. Deixe ambos de fora para manter os vínculos como estão. Editar ou excluir um registro o altera para todos os agentes aos quais ele está vinculado.

Paginação

get_agent_knowledge, list_calls e get_call_transcript recebem offset e limit e retornam um totalCount, então a página é sempre extraída do mesmo conjunto filtrado. As outras ferramentas de listagem retornam tudo em uma única resposta.

Fusos horários

Datas simples (YYYY-MM-DD) são lidas no fuso horário da empresa. Os agendamentos semanais são lidos no fuso horário de cada agente, então uma entrada vinculada a agentes em dois fusos horários segue o horário local de cada um. Passe uma data e hora completas no formato ISO 8601 quando precisar de um instante exato.

Exclusões são permanentes

Não há restauração por esta conexão. Uma habilidade, entrada de conhecimento ou ação personalizada excluída desaparece de todos os agentes aos quais estava vinculada, e esses agentes param de usá-la em poucos minutos.

Algumas configurações são apenas no painel

Voz, fuso horário e idioma; habilidades de agendamento; as conexões OAuth pelas quais uma ação personalizada autentica; excluir uma habilidade de transferência; e importar conhecimento de site são gerenciados no painel do Upfirst, não via MCP. As ferramentas indicam isso quando aplicável.

Exemplos de prompts

O servidor MCP do Upfirst funciona com qualquer cliente de IA compatível. Para começar, copie um destes prompts para o seu cliente e adapte-o ao seu negócio.

Encontre lacunas no conhecimento da sua recepcionista

Caso de uso

Use este fluxo de trabalho para revisar a semana passada de chamadas e descobrir onde o conhecimento da recepcionista ficou aquém, para saber o que adicionar ao treinamento dela.

Exemplo de prompt

Você está ajudando a encontrar lacunas no conhecimento de uma recepcionista do Upfirst.

Revise as chamadas dos últimos sete dias e depois leia o conhecimento atual da recepcionista. Procure perguntas que os chamadores fizeram e que ela não conseguiu responder bem, informações que estavam faltando e o mesmo tópico aparecendo mais de uma vez.

Para cada lacuna, aponte as chamadas que a mostram e sugira uma entrada de conhecimento específica que a preencheria, escrita da forma como a recepcionista deveria responder. Agrupe lacunas relacionadas e classifique-as pela frequência com que apareceram.

Não altere nada. Apresente as lacunas e as entradas sugeridas para revisão.

Recepcionista: [Name, or leave blank for all]

Configure sua recepcionista a partir de uma descrição

Caso de uso

Use este fluxo de trabalho para descrever como você quer que sua recepcionista lide com chamadas e deixe seu assistente montar a configuração: a saudação, o conhecimento, as regras de transferência, os agendamentos e as habilidades de mensagem de texto.

Exemplo de prompt

Você está ajudando a configurar uma recepcionista de IA do Upfirst a partir de uma descrição simples de como ela deve lidar com chamadas.

Transforme a descrição em uma configuração completa: uma saudação e uma despedida, o conhecimento necessário para responder perguntas comuns, regras de transferência para chamadas que devem chegar a uma pessoa, agendamentos para informações ou transferências que só se aplicam em determinados horários, e quaisquer habilidades de mensagem de texto que a descrição pedir.

Pergunte sobre qualquer coisa importante que a descrição deixe pouco clara, como horários, quem as chamadas devem alcançar ou como lidar com solicitações comuns, em vez de adivinhar.

Mostre a configuração completa proposta para revisão antes de criar qualquer coisa e depois aplique-a quando for aprovada.

Como a recepcionista deve lidar com chamadas: [Describe your business, your hours, what callers usually need, and who calls should reach]

Corrija uma chamada que não saiu bem

Caso de uso

Use este fluxo de trabalho para apontar uma chamada que não saiu como você queria, dizer o que você preferia e fazer seu assistente ajustar o conhecimento da recepcionista para que chamadas semelhantes saiam melhor.

Exemplo de prompt

Você está ajudando a melhorar uma recepcionista do Upfirst com base em uma chamada que não saiu bem.

Leia a chamada que eu apontar, incluindo a transcrição, e compare o que a recepcionista fez com o que eu queria que acontecesse. Descubra o que levou ao resultado: se algo no conhecimento dela estava faltando, pouco claro ou contradito por outra entrada.

Sugira as mudanças específicas que fariam uma chamada como esta sair melhor da próxima vez, escritas como o conhecimento exato a adicionar ou editar, e explique por que cada uma ajuda.

Mostre as mudanças para revisão antes de aplicá-las e depois faça as edições aprovadas.

Chamada: [ID or a short description of the call]
O que eu queria que acontecesse em vez disso: [Describe the outcome you were hoping for]

01

Conta e agentes

Oriente-se e depois leia ou atualize uma recepcionista de IA individual.

Comece aqui. Um retrato compacto de toda a conta: o nome da empresa, cada recepcionista com seu fuso horário, saudação, números de telefone, habilidades e conhecimentos, e o número de chamadas atendidas nos últimos 30 dias.

Sem parâmetros.

Retorna Nome da empresa · agentes (id, nome, fuso horário, saudação, números de telefone, nomes de habilidades e conhecimentos) · chamadas nos últimos 30 dias (somente chamadas concluídas; chamadas de teste e arquivadas não são contadas).

Liste os agentes de IA da organização. Use um ID retornado com as ferramentas de escopo de agente abaixo.

Sem parâmetros.

Retorna agentes, cada um com id e nome.

Leia as configurações conversacionais completas de um agente e os números de telefone anexados.

Parâmetro	Tipo	Descrição
agentId	string obrigatório	ID numérico do agente de list_agents.

Retorna mensagens de saudação e despedida, tom de voz, velocidade de fala, música de espera, fuso horário, bloqueio de spam e ligações gratuitas, e números de telefone anexados.

Altere as configurações conversacionais de um agente. Atualização parcial: envie apenas o que mudar; pelo menos um campo configurável é obrigatório.

Parâmetro	Tipo	Descrição
agentId	string obrigatório	Agente a atualizar.
greetingMessage	string opcional	Mensagem de abertura.
goodbyeMessage	string opcional	Mensagem de encerramento.
voiceTone	enum opcional	friendly · professional
speechRate	número opcional	0.7 · 0.85 · 1 · 1.1 · 1.2
holdMusic	enum opcional	ringTone · gentleGuitar · marimba · softKeys
isSpamCallsBlocked	booleano opcional	Bloquear chamadas suspeitas de spam.
isTollFreeCallsBlocked	booleano opcional	Bloquear chamadas gratuitas.

Voz, fuso horário e idioma são gerenciados no painel e não podem ser alterados aqui. Os dois sinalizadores de bloqueio são para toda a organização: definir qualquer um deles o altera para todos os agentes ativos, igual ao painel. greetingMessage é a saudação padrão. Saudações para determinados horários ou datas têm suas próprias ferramentas em Saudações agendadas.

Retorna o agente atualizado, no mesmo formato de get_agent_by_id.

02

Saudações agendadas

Uma saudação agendada é o que uma recepcionista diz primeiro em chamadas que caem dentro do seu agendamento, como uma saudação de after-hours ou de feriado. Cada uma pertence a um único agente. Quando nenhuma saudação agendada corresponde ao horário da chamada, o agente usa sua saudação padrão, que é lida com get_agent_by_id e alterada com update_agent.

Liste as saudações agendadas de um agente, incluindo as inativas. Leia isto antes de alterar uma saudação, para que nada seja sobrescrito sem ser visto.

Parâmetro	Tipo	Descrição
agentId	string obrigatório	Agente cujas saudações devem ser listadas.

Retorna o id de cada saudação, text, sinalizador de ativação, kind e schedule. kind é somente leitura: text significa que a saudação é falada como escrita, instruction significa que o agente constrói a saudação a partir dela e unknown significa que ainda não foi classificada.

Adicione uma saudação agendada a um agente. A saudação é salva somente quando toda a solicitação é válida.

Parâmetro	Tipo	Descrição
agentId	string obrigatório	Agente ao qual a saudação pertence.
text	string obrigatório	As palavras exatas a dizer ou uma instrução de como saudar.
schedule	objeto obrigatório	Quando a saudação é usada, no fuso horário do agente. Veja Agendamentos de saudação.
isActive	booleano opcional	Se a saudação é usada em chamadas desde o início. O padrão é true.

O agendamento não pode se sobrepor a outra saudação ativa do mesmo agente. Horários semanais e datas são verificados separadamente. kind é definido pelo sistema: ele lê unknown logo após uma gravação e é classificado em segundos.

Retorna o id da nova saudação e seus campos.

Altere o texto, o sinalizador de ativação ou o agendamento de uma saudação agendada. Atualização parcial: envie apenas o que mudar; pelo menos um campo é obrigatório.

Parâmetro	Tipo	Descrição
id	string obrigatório	Id da saudação, de list_agent_greetings.
text	string opcional	Novo texto da saudação.
isActive	booleano opcional	Se a saudação é usada em chamadas.
schedule	objeto opcional	Novo agendamento. Veja Agendamentos de saudação.

Um novo agendamento substitui o armazenado por completo, então leia a saudação primeiro e envie de volta o agendamento completo que você quer que ela tenha. A mesma regra de sobreposição se aplica como na criação. Uma alteração de texto redefine kind para unknown até que seja classificada novamente.

Retorna os campos que a atualização gravou.

Exclua permanentemente uma saudação agendada.

Parâmetro	Tipo	Descrição
id	string obrigatório	Id da saudação a excluir.

Não há como restaurar uma saudação excluída. Chamadas no intervalo de horário dela passam a usar outra saudação correspondente ou a saudação padrão do agente quando nenhuma corresponde. A programação de uma saudação tem horários semanais em days e datas exatas opcionais em dates, tudo no fuso horário do agente. days usa o mesmo formato de Programações: todos os sete dias, cada um com enabled e workingPeriods. Cada entrada em dates tem um date como YYYY-MM-DD e pelo menos um intervalo de horário em periods. Uma entrada de data tem prioridade sobre os horários semanais daquele dia, que é como você define uma saudação de feriado.

{
  "days": {
    "monday":    { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "tuesday":   { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "wednesday": { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "thursday":  { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "friday":    { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "saturday":  { "enabled": false, "workingPeriods": [] },
    "sunday":    { "enabled": false, "workingPeriods": [] }
  },
  "dates": [
    { "date": "2026-12-25", "periods": [{ "from": "00:00", "to": "23:59" }] }
  ]
}

03

Habilidades

Uma habilidade é uma ação que uma recepcionista pode executar em uma chamada: enviar mensagem de texto ao chamador, enviar um link de agendamento, transferir a chamada, agendar um compromisso ou chamar uma API externa. Cada tipo tem suas próprias ferramentas, então os campos que você envia são sempre aqueles que aquele tipo usa. Habilidades de agendamento são somente leitura aqui e gerenciadas no painel. As configurações de uma habilidade de webhook ficam na ação personalizada à qual ela está vinculada; leia e edite-as com as ferramentas de Ações personalizadas abaixo.

Liste as habilidades configuradas para um agente, incluindo as inativas por padrão.

Parâmetro	Tipo	Descrição
agentId	string obrigatório	Agente cujas habilidades serão listadas.
llmTool	enum opcional	Apenas habilidades deste tipo: sendSms · sendScheduleSms · transferCall · scheduleSlot · customWebhook.
includeInactive	boolean opcional	Incluir habilidades desativadas. Padrão true.

Retorna habilidades: id, nome, slug, tipo, flag de ativa, configuração armazenada, programação semanal opcional. Uma linha de customWebhook tem uma configuração vazia e um bloco de webhook com a url da ação vinculada, método HTTP e temporização; leia sua configuração completa com list_custom_actions.

Uma programação é respeitada em chamadas apenas para habilidades de transferência. Outros tipos armazenam uma, mas a ignoram.

Adicione uma habilidade de mensagem de texto: um SMS que a recepcionista pode enviar a um chamador durante uma chamada. sendSms envia a mensagem como escrita. sendScheduleSms a envia junto com o link de agendamento da organização.

Parâmetro	Tipo	Descrição
agentIds	string[] obrigatório	Agentes que recebem a habilidade, pelo menos um. Ids de list_agents.
autoLinkNewAgents	boolean opcional	Também dar a habilidade a todo agente criado posteriormente. Quando true, agentIds deve listar todos os agentes atuais. Padrão false.
llmTool	enum obrigatório	sendSms · sendScheduleSms
name	string obrigatório	Rótulo curto, exibido no painel.
message	string obrigatório	O texto do SMS que o agente envia, até 306 caracteres.
instruction	string obrigatório	Quando o agente deve enviá-lo durante uma chamada.
isActive	boolean opcional	Ativada desde o início. Padrão true.

A mensagem passa por um filtro de conteúdo que rejeita redação promocional ou de outra forma restrita.

Retorna o id da nova habilidade e os campos que você enviou (llmTool, name, message, instruction, isActive). Leia a habilidade armazenada com list_agent_skills.

Altere uma habilidade de mensagem de texto. Atualização parcial: apenas os campos que você enviar mudam. Envie pelo menos um campo configurável ou um novo conjunto de agentes.

Parâmetro	Tipo	Descrição
skillId	string obrigatório	Id da habilidade de list_agent_skills.
llmTool	enum opcional	Alternar entre sendSms e sendScheduleSms.
name	string opcional	Novo rótulo.
message	string opcional	Novo texto do SMS, até 306 caracteres.
instruction	string opcional	Nova orientação sobre quando enviá-lo.
isActive	boolean opcional	Ativar ou desativar a habilidade.
agentIds	string[] opcional	Novo conjunto de agentes que recebem a habilidade. Envie junto com autoLinkNewAgents, ou omita ambos para manter os vínculos atuais.
autoLinkNewAgents	boolean opcional	Também dar a habilidade a todo agente criado posteriormente. Quando true, agentIds deve listar todos os agentes atuais.

Retorna os campos que a atualização gravou.

Exclua permanentemente uma habilidade de mensagem de texto de todos os agentes aos quais ela está vinculada. Esses agentes param de enviar essa mensagem.

Parâmetro	Tipo	Descrição
skillId	string obrigatório	Id da habilidade a excluir.

Não há como restaurar uma habilidade excluída. Recuperá-la significa criá-la novamente do zero.

Retorna { id, note }, onde note confirma a exclusão em linguagem simples.

Adicione uma habilidade de transferência: a regra que entrega uma chamada ao vivo a uma pessoa. condition diz ao agente quando transferir, preTransferMessage é o que ele diz ao chamador primeiro, e destinations são os números que ele disca em ordem.

Parâmetro	Tipo	Descrição
agentIds	string[] obrigatório	Agentes que recebem a habilidade, pelo menos um. Ids de list_agents.
autoLinkNewAgents	boolean opcional	Também dar a habilidade a todo agente criado posteriormente. Quando true, agentIds deve listar todos os agentes atuais. Padrão false.
name	string obrigatório	Rótulo curto, exibido no painel.
condition	string obrigatório	Quando transferir, em linguagem simples.
preTransferMessage	string obrigatório	O que o agente diz antes de transferir.
destinations	array obrigatório	Um ou mais destinos, tentados em ordem, cada { phoneNumber, label, phoneExtension }. phoneNumber é obrigatório e deve estar em E.164 (ex.: +12025550123).
ringTimeoutSeconds	number opcional	Tempo de toque por destino, 5–60.
noAnswerAction	enum opcional	endCall · returnToAgent
transferMethod	enum opcional	cold transfere o chamador diretamente · warm informa o destino primeiro.
transferCallerId	enum opcional	Número que o destino vê: upfirstNumber · callerNumber.
recordingMode	enum opcional	agentOnly interrompe a gravação na transferência · fullCall continua gravando depois dela.
isActive	boolean opcional	Ativada desde o início. Padrão true.
schedule	object opcional	Horários semanais em que a habilidade é oferecida, no fuso horário do agente. Omita para disponibilidade total. Veja Programações.

Cada destino deve estar no mesmo país que um dos números Upfirst dos agentes vinculados. Quando omitido, a habilidade usa os padrões do painel no momento da chamada: toque de 30 segundos, encerrar a chamada se não houver resposta, transferência fria, o número Upfirst como identificador de chamadas e gravação interrompida na transferência.

Retorna o id da nova habilidade e os campos que você enviou. Leia a habilidade armazenada com list_agent_skills.

Altere uma habilidade de transferência. Atualização parcial: apenas os campos que você enviar mudam. Envie pelo menos um campo configurável ou um novo conjunto de agentes.

Parâmetro	Tipo	Descrição
skillId	string obrigatório	Id da habilidade de list_agent_skills.
destinations	array opcional	Substitui a lista inteira. Envie todos os números que deseja manter.
schedule	object opcional	Substitui os horários armazenados. null limpa a programação, tornando a habilidade disponível 24 horas por dia.
Outros campos de criação	opcional	name, condition, preTransferMessage, ringTimeoutSeconds, noAnswerAction, transferMethod, transferCallerId, recordingMode, isActive. Mesmos valores da criação.
agentIds	string[] opcional	Novo conjunto de agentes que recebem a habilidade. Envie junto com autoLinkNewAgents, ou omita ambos para manter os vínculos atuais.
autoLinkNewAgents	boolean opcional	Também dar a habilidade a todo agente criado posteriormente. Quando true, agentIds deve listar todos os agentes atuais.

Cada destino deve estar no mesmo país que um dos números Upfirst dos agentes vinculados.

O tipo de uma habilidade é fixo na criação. Passar o id de uma habilidade de agendamento ou webhook é lido como não encontrado.

Retorna os campos que a atualização gravou.

Não há ferramenta para isso. Habilidades de transferência são excluídas no painel Upfirst. Pelo MCP você pode desativar uma: defina isActive: false com update_transfer_call_skill, e o agente para de oferecer a transferência enquanto a habilidade permanece configurada.

04

Conhecimento

O conhecimento de uma recepcionista é aquilo com que ela responde aos chamadores. No painel Upfirst, essas entradas ficam em Treinamento. Cada uma é um texto que você escreve ou conteúdo importado de um site. Uma entrada pode ser vinculada a vários agentes, e editá-la ou excluí-la muda o que cada agente vinculado responde. Gravações retreinam a recepcionista automaticamente em minutos.

Leia a base de conhecimento de um agente. Cada entrada é retornada inteira com seu conteúdo completo, nunca uma prévia.

Parâmetro	Tipo	Descrição
agentId	string obrigatório	Agente cujo conhecimento será lido.
id	string opcional	Retornar apenas esta entrada.
offset	number opcional	Entradas a pular. Padrão 0.
limit	number opcional	Máximo de entradas, 1–100. Padrão 25.

Retorna entradas: id, nome, tipo (texto/site), flag de ativa, conteúdo completo, url de origem e programação semanal, além de totalCount.

Adicione uma entrada de texto ao treinamento de uma ou mais recepcionistas. A nova entrada vai para o topo da lista de cada agente vinculado.

Parâmetro	Tipo	Descrição
agentIds	string[] obrigatório	Agentes que recebem a entrada, pelo menos um. Ids de list_agents.
autoLinkNewAgents	boolean opcional	Também dar a entrada a todo agente criado posteriormente. Quando true, agentIds deve listar todos os agentes atuais. Padrão false.
name	string obrigatório	Nome de exibição da entrada.
content	string obrigatório	Texto simples, até 250.000 caracteres.
isActive	boolean opcional	Ativa desde o início. Padrão true.
schedule	object opcional	Restringir a entrada ao horário comercial. Omita para sempre ativa. Veja Programações.

Retorna o id, name, isActive, schedule (null quando sempre ativa) da nova entrada e contentLength em caracteres. Leia a entrada completa com get_agent_knowledge.

Altere o nome, a flag de ativa, o conteúdo, a programação ou quais agentes veem uma entrada. Atualização parcial: envie pelo menos um campo configurável ou um novo conjunto de agentes.

Parâmetro	Tipo	Descrição
id	string obrigatório	Id da entrada de get_agent_knowledge.
name, isActive	opcional	Novo nome / flag de ativa.
content	string opcional	Novo texto, substituindo o conteúdo armazenado inteiramente. Até 250.000 caracteres.
schedule	object opcional	Nova programação. null a limpa, tornando a entrada sempre disponível; omita para manter a armazenada.
agentIds	string[] opcional	Novo conjunto de agentes que recebem a entrada. Envie junto com autoLinkNewAgents, ou omita ambos para manter os vínculos atuais.
autoLinkNewAgents	boolean opcional	Também dar a entrada a todo agente criado posteriormente. Quando true, agentIds deve listar todos os agentes atuais.

O conteúdo é substituído, nunca anexado. Leia a entrada com get_agent_knowledge primeiro e envie de volta o texto completo que deseja que ela tenha, incluindo o que está mantendo. A edição muda o que todo agente vinculado à entrada diz.

Retorna os campos que a atualização gravou. Novo conteúdo volta como contentLength, não como o texto completo.

Exclua permanentemente uma entrada de conhecimento.

Parâmetro	Tipo	Descrição
id	string obrigatório	Id da entrada a excluir.

Não há como restaurar uma entrada excluída. Excluí-la a remove de todo agente ao qual está vinculada.

Retorna { id, note }, onde note confirma a exclusão em linguagem simples. Uma programação restringe uma entrada de conhecimento (ou habilidade de transferência) ao horário comercial, respeitado no fuso horário comercial do agente. É um objeto por dia da semana. Toda programação que você enviar deve incluir todos os sete dias; um dia em que a entrada não deve se aplicar é enabled: false com um workingPeriods vazio. Os horários são em formato HH:MM de 24 horas no fuso horário do agente.

Uma entrada programada só está no conhecimento da recepcionista durante suas janelas. Fora delas, é como se a entrada não existisse, então a recepcionista nunca responde com base nela no momento errado.

Isso torna as programações uma forma confiável de lidar com fatos específicos de tempo. Para tornar os horários de abertura e fechamento à prova de erros, adicione uma entrada restrita aos seus horários de funcionamento que diga "Estamos abertos no momento" e uma segunda restrita aos seus horários de fechamento que diga "Estamos fechados no momento". Apenas uma está ativa por vez, então a recepcionista não pode confundi-las.

{
  "days": {
    "monday":    { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "tuesday":   { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "wednesday": { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "thursday":  { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "friday":    { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "saturday":  { "enabled": false, "workingPeriods": [] },
    "sunday":    { "enabled": false, "workingPeriods": [] }
  }
}

05

Ações personalizadas

Uma ação personalizada é uma chamada que a recepcionista faz a uma API HTTP externa. timing decide quando ela é executada: before dispara antes da conversa e só pode usar variáveis de sistema; during é oferecida ao agente na chamada, que decide pela descrição se deve chamá-la; after dispara quando a chamada termina, seja sempre ou quando uma condição em linguagem natural for atendida.

Variáveis são interpoladas na url, nos parâmetros de consulta, nos cabeçalhos e no corpo como {{name}}. Uma ação está vinculada a um ou mais agentes, e editá-la ou excluí-la altera o que cada agente vinculado faz. Em list_agent_skills, uma habilidade customWebhook é a visão do lado do agente de uma ação personalizada. As conexões OAuth pelas quais uma ação pode autenticar são configuradas no painel da Upfirst.

Toda ação personalizada que um agente pode usar, cada uma com sua configuração completa. Leia isto antes de reescrever uma ação, para que nada seja sobrescrito sem ser visto.

Parâmetro	Tipo	Descrição
agentId	string obrigatório	Agente cujas ações devem ser listadas. Toda ação vinculada a este agente é incluída.
id	string opcional	Retorna apenas esta ação.

Retorna customActions, cada uma com id, agentIds (todo agente ao qual a ação está vinculada), autoLinkNewAgents, nome, descrição, momento, método HTTP, url, tipo de autenticação e id da conexão OAuth, mensagem de fallback, tempo limite, sinalizador ativo, variáveis, parâmetros de consulta, cabeçalhos, campos de saída permitidos, valores de amostra, modelo de corpo e a condição do momento posterior.

Um cabeçalho cujo nome parece uma credencial (token, chave, segredo, autorização) retorna como [redacted]; o valor real nunca é lido. Ações excluídas são omitidas.

Adiciona uma ação personalizada e a vincula a um ou mais agentes.

Parâmetro	Tipo	Descrição
agentIds	string[] obrigatório	Agentes que recebem a ação, pelo menos um. Ids de list_agents.
autoLinkNewAgents	booleano opcional	Também dá a ação a todo agente criado posteriormente. Quando true, agentIds deve listar todo agente atual. Padrão false.
name	string obrigatório	Rótulo curto, exibido no painel.
description	string obrigatório	O que a ação faz, em linguagem natural. O momento before e during a coloca diante do agente, que decide por este texto se deve chamar a API. O momento after a ignora.
timing	enum obrigatório	before · during · after
httpMethod	enum obrigatório	GET · POST · PUT · PATCH · DELETE
url	string obrigatório	Endpoint para onde a solicitação vai. Pode conter espaços reservados {{variable}}.
authType	enum obrigatório	none envia a solicitação sem autenticação · bearer precisa de um cabeçalho Authorization em headers · customHeaders autentica pelos cabeçalhos que você fornece · oauth_connection resolve um token de uma conexão e precisa de oauthConnectionId.
fallbackMessage	string obrigatório	O que o agente diz ao chamador quando a solicitação falha ou expira.
oauthConnectionId	string opcional	Id numérico de uma conexão OAuth conectada. Obrigatório para oauth_connection, rejeitado para todo outro tipo de autenticação. Tire-o de list_custom_actions em uma ação que já usa uma.
variables	array opcional	Valores interpolados na solicitação, cada um { name, description, exampleValue, isSystem, required }. name e description são obrigatórios e os nomes devem ser únicos. Variáveis de sistema são preenchidas pela Upfirst a partir da própria chamada; as personalizadas são coletadas do chamador. Uma ação de momento before só pode usar variáveis de sistema. Padrão [].
queryParams	array opcional	Parâmetros de string de consulta, cada um { key, value }. Valores podem usar espaços reservados. Padrão [].
headers	array opcional	Cabeçalhos de solicitação, cada um { key, value }. A autenticação Bearer carrega seu token em um cabeçalho Authorization aqui. Nunca envie o espaço reservado [redacted] de volta. Padrão [].
allowedOutputFields	string[] opcional	Campos da resposta JSON que o agente pode ler. Vazio passa a resposta intacta. Padrão [].
bodyTemplate	string opcional	Corpo da solicitação enviado como está com espaços reservados substituídos. Vazio para nenhum.
sampleValues	objeto opcional	Um valor por nome de variável, usado quando a ação é testada.
timeoutSeconds	inteiro opcional	1–30. Padrão 10.
isActive	booleano opcional	Ativada desde o início. Padrão true.
condition	string ou nulo opcional	Somente momento after. Regra em linguagem natural verificada contra a chamada concluída; null dispara após toda chamada. Deixe de fora para before e during.

Retorna a ação criada com seu novo id.

Altera uma ação personalizada. Atualização parcial: apenas os campos que você enviar mudam. Envie pelo menos um campo configurável ou um novo conjunto de agentes. Listas são substituídas inteiras, não mescladas, então leia a ação com list_custom_actions primeiro.

Parâmetro	Tipo	Descrição
id	string obrigatório	Id da ação de list_custom_actions.
agentIds	string[] opcional	Novo conjunto de agentes que recebem a ação. Envie junto com autoLinkNewAgents, ou deixe ambos de fora para manter os vínculos atuais.
autoLinkNewAgents	booleano opcional	Também dá a ação a todo agente criado posteriormente. Quando true, agentIds deve listar todo agente atual.
oauthConnectionId	string ou nulo opcional	null o limpa. Envie null na mesma chamada que move a ação para fora do tipo de autenticação oauth_connection.
condition	string ou nulo opcional	null o limpa. Envie null na mesma chamada que move a ação para fora do momento after.
variables, queryParams, headers, allowedOutputFields	array opcional	Cada um substitui sua lista inteira. Envie toda entrada que quiser manter. Um cabeçalho que carrega o espaço reservado [redacted] é recusado; envie o valor real ou deixe esse cabeçalho de fora.
Outros campos de criação	opcional	name, description, timing, httpMethod, url, authType, bodyTemplate, sampleValues, fallbackMessage, timeoutSeconds, isActive. Mesmos valores da criação.

Uma ação vinculada a vários agentes é editada para todos eles.

Retorna os campos que a atualização gravou.

Exclui permanentemente uma ação personalizada. Todo agente vinculado a ela para de chamar essa API.

Parâmetro	Tipo	Descrição
id	string obrigatório	Id da ação a excluir.

Não há como restaurar uma ação excluída. Recuperá-la significa criá-la novamente do zero, e list_custom_actions retorna sua configuração apenas enquanto ela ainda existe.

Retorna { id, note }, onde note confirma a exclusão em linguagem natural.

06

Chamadas

Leia o histórico de chamadas da empresa, os detalhes de uma chamada e sua transcrição. Apenas chamadas concluídas aparecem; uma chamada aparece pouco depois de terminar.

Lista e filtra o histórico de chamadas, mais recentes primeiro. Linhas compactas sem transcrições ou resumos (use as ferramentas abaixo para esses).

Parâmetro	Tipo	Descrição
statuses	enum[] opcional	Filtra por resultado, cada chamada tem exatamente um: test · blocked · spam · hungUp · completed.
query	string opcional	Busca de texto livre sobre resumos e transcrições de chamadas.
tags	string[] opcional	Corresponde a chamadas que carregam qualquer uma dessas tags (por nome ou id).
startDate	data opcional	YYYY-MM-DD puro = dia do calendário no fuso horário comercial, ou um datetime ISO completo.
endDate	data opcional	Como acima; inclusivo.
archived	booleano opcional	Retorna chamadas arquivadas em vez de ativas. Padrão false.
offset, limit	número opcional	Paginação. limit é 1–100, padrão 25.

Retorna linhas de chamadas (chamador, hora, duração, resultado, tags, contato vinculado, contagem de turnos de transcrição) mais totalCount.

Detalhes completos de uma chamada, tudo exceto o texto da transcrição e a gravação.

Parâmetro	Tipo	Descrição
callId	string obrigatório	Id numérico da chamada de list_calls.

Retorna momento, resultado, números do chamador e da recepcionista, o resumo escrito por IA, campos de dados capturados, as habilidades que o agente usou (com quando cada uma disparou), tags, comentários da sua equipe e a contagem de turnos de transcrição.

O texto da conversa de uma chamada como turnos ordenados, cada um carimbado com um deslocamento [mm:ss] e seu falante.

Parâmetro	Tipo	Descrição
callId	string obrigatório	Id numérico da chamada de list_calls.
offset, limit	número opcional	Paginação sobre turnos. limit é 1–200, padrão 100. Uma chamada típica cabe em uma resposta; pagine apenas quando a nota disser que mais turnos permanecem.

Falantes são Agente (a recepcionista de IA), Chamador (a pessoa que ligou) e Transferido (um humano para quem a chamada foi passada).

Retorna turnos (deslocamento, falante, texto) mais totalCount.

FAQ

Como faço para a Upfirst começar a atender minhas chamadas?

Nós damos a você um número de telefone. Você pode divulgar esse número e fazer as pessoas ligarem diretamente, mas a maioria das empresas encaminha chamadas para ele a partir da linha que já usam.

Você escolhe quanto encaminhar: toda chamada, apenas as que você perde ou, dependendo do seu telefone, operadora ou sistema VoIP, apenas durante certos horários. Os passos diferem para cada provedor, então veja Encaminhe todas as suas chamadas para a Upfirst para o seu.

Preciso de uma chave de API?

Não. A autorização é um login padrão OAuth 2.1. A primeira chamada abre a página de login da Upfirst, você aprova o acesso uma vez, e não há nada para copiar, colar ou armazenar.

Com quais assistentes de IA posso usar isso?

Qualquer cliente que suporte servidores MCP remotos sobre HTTP. A seção Conectando tem configuração para Claude, ChatGPT, Claude Code, Cursor, VS Code e Codex. Para qualquer outra coisa, aponte para https://mcp.upfirst.ai como um servidor HTTP transmissível e ele lidará com o login na primeira chamada.

O que meu assistente pode acessar?

Apenas a organização na qual você fez login. Toda ferramenta é limitada a essa organização, e ids de qualquer outra nunca são acessíveis. Dentro dela, o assistente pode ler chamadas e transcrições e alterar configurações da recepcionista, habilidades, conhecimento e ações personalizadas, e escolher a quais recepcionistas cada uma se aplica, então trate a conexão como trataria estar logado no painel.

Por que uma chamada que acabei de atender não aparece? Apenas chamadas concluídas aparecem, e uma chamada é exibida pouco depois de terminar. Chamadas em andamento não ficam disponíveis até que sejam encerradas. Se uma chamada ainda estiver ausente, verifique se ela foi arquivada, pois list_calls retorna chamadas ativas, a menos que você passe archived: true.

O que não posso fazer via MCP?

Voz, fuso horário e idioma; habilidades de agendamento; conexões OAuth para ações personalizadas; exclusão de uma habilidade de transferência; e importação de conhecimento de um site são todos gerenciados no painel do Upfirst. Gravações de chamadas também não estão disponíveis por esta conexão. As ferramentas indicam isso quando aplicável.