Chaves e acesso
O agente entra no Felku com uma chave, enviada no cabeçalho Authorization: Bearer <chave>. A sessão do painel (o seu login) não vale no MCP, e a chave não vale no painel.
Criar uma chave
No painel, em Agentes e chaves, crie a chave com:
Nome, para você saber qual agente usa a chave.
Conexão (opcional): a chave fica presa ao canal dessa conexão (WhatsApp ou Telegram): o agente só vê e só usa as ferramentas daquele canal. Se a conexão for apagada (ao descer de plano ou quando uma conexão pausada passa do prazo), as chaves presas a ela são revogadas e nunca viram chaves livres. Desconectar o número não apaga a conexão: as chaves continuam presas a ela.
Permissões (escopos): o que o agente pode fazer, veja abaixo. No painel, a chave já vem só com as de leitura marcadas; marque as de envio só se o agente precisar. Não dá para mudar as permissões depois: para isso, revogue a chave e crie outra.
Validade (opcional): a chave para de funcionar sozinha na data escolhida.
A chave começa com fkc_ e aparece completa uma única vez. Guardamos só uma impressão dela (hash) e os primeiros 8 caracteres, para você reconhecê-la na lista, junto com a data do último uso. Se perder, revogue e crie outra.
Para criar chave, a conta precisa de um plano ativo ou no período de teste, e do e-mail confirmado.
Permissões (escopos)
| Escopo | Libera |
|---|---|
whatsapp:read | ler mensagens novas do WhatsApp (felku_read_new_messages) e, em grupos, comunidades e canais: felku_list_groups, felku_read_group_messages, felku_list_available_groups, felku_list_communities, felku_get_community, felku_get_group_info, felku_list_labels, felku_newsletter_info, felku_newsletter_read_messages |
whatsapp:write | enviar e agir no WhatsApp: texto, marcar como lido, reagir, digitando, verificar número, editar e apagar mensagem própria (felku_send_text, felku_mark_read, felku_react, felku_set_typing, felku_check_number, felku_edit_message, felku_delete_message) Mais: felku_star_message, felku_create_label, felku_label_chat, felku_label_message, felku_newsletter_follow e as de escrever e administrar grupos, comunidades e canais |
telegram:read | ler mensagens do bot de Telegram (felku_telegram_read_updates) |
telegram:write | enviar pelo bot (felku_telegram_send_message) |
connections:read | ver o status das conexões e o uso dos limites (felku_get_connection_status, felku_get_policy_status) |
connections:write | pedir o link de pareamento e pausar uma conexão (felku_start_pairing, felku_pause_connection) |
Chave criada sem escolher escopos (pela API) nasce só com leitura: connections:read, whatsapp:read e telegram:read (quando o plano tem Telegram). Para enviar, peça os de envio. O agente só vê as ferramentas que a chave permite: tools/list já vem filtrado. Se ele não acha uma ferramenta (Unknown tool), a chave não tem a permissão dela.
Há também permissões elevadas, que nunca entram sozinhas: só se você pedir de propósito.
| Escopo elevado | Libera |
|---|---|
risk:high | as ações de risco alto, que vêm desligadas. Sozinho ele não libera as ferramentas de grupo, comunidade e canal: elas pedem o action: específico. |
action:<tipo> | libera só uma ação específica de risco alto. No WhatsApp, para grupos, comunidades e canais: action:group_read_enable (pedir a liberação de leitura), action:group_send_enable e action:group_send (liberar e enviar a grupo, avisos de comunidade), action:channel_react, action:group_create, action:group_add, action:group_manage, action:community_manage, action:channel_admin. |
As ferramentas de grupo, comunidade e canal estão em Ferramentas. A tela de criar chave do painel hoje não oferece as action:...: elas só entram numa chave criada pela API.
Boas práticas:
Uma chave por agente. Assim você revoga um sem derrubar os outros.
O mínimo necessário. Um agente que só resume conversas precisa só de
whatsapp:read(econnections:readpara ver o status). Atenção: até marcar como lido e reagir pedemwhatsapp:write, porque aparecem para a outra pessoa.Só um agente com permissão de envio por conexão, para não responder em dobro (cada chave lê as mensagens pelo próprio cursor).
Quantas chaves cada plano tem
| Plano | Conexões | Chaves |
|---|---|---|
| Teste de 7 dias | 1 | 2 |
| Pessoal | 1 | 2 |
| Pro | 5 | 10 |
| Empresa | 15 | 50 |
Plano maior não aumenta os limites de envio: as travas são as mesmas para todos (por quê).
Antes de conectar um canal
A chave só funciona depois que a conta conectou o WhatsApp ou o Telegram. Antes disso, todo pedido ao MCP (inclusive initialize e tools/list) volta com HTTP 403 e o código connection_required, com a mensagem "Your key is valid, but no channel is connected yet...". A chave está certa: conecte um canal no painel, em Conexões › Nova conexão, e tente de novo.
Revogar
No painel, em Agentes e chaves, revogue a chave. Ela para de funcionar na hora (o próximo pedido volta unauthorized). Se suspeitar de vazamento: revogue a chave, pause ou desconecte o número e troque a senha da conta.
Quando a assinatura não permite enviar
Se o pagamento estiver recusado e a carência de 7 dias tiver acabado, ou se a assinatura for cancelada, as chaves perdem as permissões de envio (todas as :write). A leitura continua, para você conseguir consultar e apagar os seus dados.
Respostas de acesso
| HTTP | Código | O que significa |
|---|---|---|
| 401 | unauthorized | chave ausente, errada, vencida ou revogada |
| 403 | connection_required | a chave é válida, mas a conta ainda não conectou nenhum canal. Conecte o WhatsApp ou o Telegram no painel |
| 403 | not_your_connection | a chave é válida, mas não pode usar esta conexão (pertence a outra conta) |
| 405 | method_not_allowed | o servidor MCP só aceita POST |
Chave presa a uma conexão que tenta usar ferramenta do outro canal não é recusada no HTTP: a chamada volta normalmente, com o erro key_bound_to_other_channel no resultado da ferramenta. Use uma chave da conexão certa (ou uma chave sem conexão presa).