Pular para o conteúdo
NovoVeja como

Usando o FirstSales com o Gemini

Conecte o Gemini ao FirstSales via API REST com ferramentas de função restritas — leia antes de escrever, escopos por ferramenta e mutações seguras e verificáveis.

Tutoriais
Desenvolvedor e CLI
min de leitura
8 min
etapas
6 · Avançado

  1. Duas formas de conectar o Gemini

    Se o seu ambiente Gemini (por exemplo, o Gemini CLI com acesso a shell) puder rodar npm, instale o @firstsales.io/cli e exponha-o como uma ferramenta: ele cuida da autenticação, do JSON e da idempotência. Se o Gemini funcionar apenas via API, chame a Developer API da FirstSales por HTTPS a partir das implementações da sua função/ferramenta. A documentação classifica o Gemini junto com os agentes que priorizam a API por padrão.

  2. Guarde a chave fora do modelo

    Crie uma chave da Developer API em Settings → API e mantenha-a na configuração server-side do seu app como FIRSTSALES_API_KEY. O Gemini deve chamar uma tool/function que lê a chave no lado do servidor: o próprio modelo nunca deve ver ou emitir a chave bruta.

    FIRSTSALES_API_KEY=fs-key-...
FIRSTSALES_BASE_URL=https://api.app.firstsales.io

  3. Defina ferramentas restritas, não uma porta de escape HTTP genérica

    Dê ao Gemini um pequeno conjunto de funções feitas sob medida (whoami, list_contacts, create_contact, campaign_analytics) cada uma mapeada para um endpoint público. Isso mantém o modelo na superfície suportada, em vez de deixá-lo construir URLs arbitrárias.

    # o que cada tool chama por baixo dos panos
GET  /api/v1/whoami
GET  /api/v1/organizations/{org}/workspaces/{ws}/contacts
POST /api/v1/organizations/{org}/workspaces/{ws}/contacts     # Idempotency-Key
GET  /api/v1/organizations/{org}/workspaces/{ws}/campaigns/{id}/analytics

  4. Verifique a identidade na primeira chamada de ferramenta

    Faça o agente chamar whoami antes de qualquer escrita, para confirmar o contexto de org e workspace:

    curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

  5. Escreva de forma idempotente a partir da sua tool de criação

    Sua tool create_contact deve sempre anexar um Idempotency-Key, para que uma chamada de função repetida não gere uma escrita duplicada:

    curl -X POST \
  https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-lead-2026-01" \
  -d '{"email":"[email protected]","first_name":"Sam"}'

  6. Trate erros e permaneça na superfície pública

    Em cada tool, trate 401 (chave inválida/revogada), 422 (validação (exiba o campo) e 429 (recue e tente novamente). Em unsupported_operation, retorne a limitação ao modelo e pare) nunca deixe o Gemini raspar o app ou acessar rotas privadas, callbacks, pixels ou endpoints de cron.

Dicas de especialista

  • Empacote endpoints como ferramentas restritas

    Não entregue ao Gemini uma função genérica de 'chamar qualquer URL'. Ferramentas feitas sob medida (create_contact, campaign_analytics) mantêm o modelo na superfície pública e tornam suas ações auditáveis.

  • O modelo nunca toca na chave

    Leia FIRSTSALES_API_KEY no lado do servidor, dentro da ferramenta. Se a chave puder aparecer no contexto ou na saída do modelo, ela pode vazar para os logs.

  • whoami como primeira chamada de função

    Torne a verificação de identidade o primeiro passo, para que o Gemini sempre confirme org/workspace antes de escrever.

  • Tem shell disponível? O CLI é menos código

    Se o Gemini CLI tiver shell + npm, chamar o firstsales via shell é melhor do que criar ferramentas HTTP na mão: autenticação, JSON, idempotência e confirmação de exclusão vêm de graça.

Perguntas frequentes

O Gemini usa o CLI ou a API?

Por padrão, a Developer API, empacotada como functions/tools. Se o seu ambiente Gemini tiver acesso a shell com npm, o CLI é uma alternativa de menor esforço que cuida da autenticação e da idempotência para você.

Como mantenho a chave longe do modelo?

Guarde FIRSTSALES_API_KEY na configuração server-side e leia-a dentro da implementação da ferramenta. O modelo chama a ferramenta; ele nunca vê ou emite a chave bruta.

Como devo estruturar as ferramentas?

Como funções restritas e de propósito único: uma por endpoint público (whoami, listar/criar contato, campaign analytics). Evite uma tool genérica de 'buscar qualquer URL' que permita ao modelo sair da superfície suportada.

Como evito escritas duplicadas?

Anexe um cabeçalho Idempotency-Key dentro da sua tool de criação. Uma chamada de função repetida com a mesma chave retorna o resultado original em vez de criar um duplicado.

O que está fora dos limites?

Rotas privadas do app, callbacks de provedores, pixels de rastreamento, handlers de descadastro, endpoints internos de cron e raspagem da UI. Fique na /api/v1 pública; pare em unsupported_operation.

Desenvolvedor e CLI

Prospecção que continua quando você desconecta.Leads, emails, follow-ups e respostas, resolvidos.

Conecte caixas ilimitadas e deixe os agentes de IA encontrarem leads, escreverem cada email e fazerem follow-up. Ou envie seus próprios modelos no modo manual. A partir de $29/mês.

Comece seu teste de $1 Ver preços

$1 por 3 dias · Cancele quando quiser · Sem contrato

Instalar com IA

Seu agente de código configura a CLI e as skills do FirstSales para você.

Prompt para Claude Code

I'm setting up FirstSales (https://firstsales.io), an AI outbound sales platform: campaigns, contacts, a reply inbox, deliverability and lead signals. Help me get my workspace sending real, good emails end to end, from Claude Code.

Read these first so you know how FirstSales works:
- Developer docs and API: https://developer.firstsales.io
- CLI: https://www.npmjs.com/package/@firstsales.io/cli
- Skills for coding agents: https://github.com/firstsalesio/firstsales-skills (read README.md and GUIDE.md)

Setup
1. Install the CLI: npm install -g @firstsales.io/cli
2. Install the FirstSales skills:
   claude plugin marketplace add firstsalesio/firstsales-skills
   claude plugin install firstsales@firstsales
3. Ask me if I already have a FirstSales account. If not, send me to https://app.firstsales.io to sign up.
4. Ask me to create an API key under Settings → API → API Keys, with only the scopes we need.
   Never ask me to paste the key into this chat. Tell me to run this in my own terminal, so the key stays hidden:
   read -rs FS_KEY && firstsales auth login --api-key "$FS_KEY"; unset FS_KEY
5. Run `firstsales whoami` and tell me which workspace and organisation we are connected to.

Then ask me about my business: what I sell, who I sell to (roles, company size, countries), my best customers, and what I use today for outbound (tools, lists, mailboxes). Walk me through:
1. Teaching FirstSales my business: website, offer, proof points and case studies in the knowledge base, so the AI writes like someone who knows the product.
2. Connecting my sending mailboxes and checking my sending domain: SPF, DKIM, DMARC and warm-up. If anything is unhealthy, tell me the exact DNS record to add.
3. Bringing in contacts: import my CSV or CRM export into a clean list, remove duplicates and bad emails, and block domains I must never email (customers, competitors, my own).
4. Building my first campaign: the right list, senders, steps and timing. Write the sequence with me, show me the drafts, and do not launch until I say yes.
5. Setting up Signals if it fits: find people engaging with LinkedIn posts about topics my buyers care about, and turn them into leads.
6. Inviting my team and giving each person the right access.

Once campaigns run, show me how to work the reply inbox from here: which replies need an answer, draft responses in my voice, and move good conversations into deals. If I use Cal.com, connect it so follow-ups can offer my booking link (not the first email).

Throughout, as you learn about my business, proactively suggest and help create:
- Reply templates for the questions and objections my prospects are likely to raise, based on my product, site and codebase if you can see them.
- Campaign ideas and segments worth testing, with the reason for each.

Safety rules:
- Show every change as a dry run (--dry-run) first and wait for my yes. Never send emails, launch campaigns or delete anything without my yes.
- Tell me before anything that spends credits, and how many.

Be opinionated. If the docs give a sensible default, just use it. Don't make me choose between five options.
Developer docs ↗npm: @firstsales.io/cli ↗GitHub: firstsales-skills ↗