Pular para o conteúdo
NovoVeja como

Usando o FirstSales com o Codex

Conecte o Codex ao FirstSales via API REST (ou CLI em um shell) — primeira chamada whoami, chaves com escopo restrito, escritas idempotentes e interrupção em operações não suportadas.

  1. Escolha o caminho certo para sua configuração do Codex

    O FirstSales oferece dois caminhos de integração. Se o seu ambiente Codex tem shell com npm, instale o @firstsales.io/cli e controle-o como qualquer agente com shell: ele cuida de autenticação, JSON e idempotência para você. Se o Codex roda sem acesso a shell (navegador ou sandbox), chame a Developer API diretamente via HTTPS. A documentação agrupa o Codex com agentes API-first exatamente por esse motivo.

  2. Guarde a chave como um secret de ambiente

    Crie uma chave de API de desenvolvedor em Settings → API e coloque-a no cofre de secrets do seu ambiente Codex como FIRSTSALES_API_KEY. Nunca cole a chave crua em um prompt nem a commite: referencie a variável de ambiente no código.

    # no ambiente da sua tarefa do Codex
    FIRSTSALES_API_KEY=fs-key-...
    FIRSTSALES_BASE_URL=https://api.app.firstsales.io
  3. Verifique a identidade primeiro

    Qualquer que seja o caminho, a primeira chamada confirma que a chave resolve para a org e o workspace esperados:

    curl https://api.app.firstsales.io/api/v1/whoami \
      -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  4. Leia o estado antes de escrever

    Faça o Codex inspecionar antes de mutar. Os recursos são vinculados a org e workspace:

    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/campaigns \
      -H "Authorization: Bearer $FIRSTSALES_API_KEY"
    
    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
      -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  5. Escreva de forma idempotente

    Em criações, envie um header Idempotency-Key para que uma requisição repetida nunca duplique dados: importante para um agente autônomo que pode repetir a chamada em caso de timeout:

    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: codex-lead-2026-01" \
      -d '{"email":"[email protected]","first_name":"Sam"}'
  6. Mantenha o Codex na superfície pública

    Instrua o Codex a usar apenas os endpoints públicos /api/v1. Em uma resposta unsupported_operation, ele deve parar e reportar (nunca raspar o app ou chamar rotas privadas, callbacks de provedores, pixels de rastreamento, handlers de descadastro ou endpoints de cron para forçar um resultado. Trate 401 (chave errada), 422 (validação) o corpo nomeia o campo) e 429 (recue) explicitamente.

Dicas de especialista

  • Tem shell? Prefira a CLI

    Se o seu sandbox do Codex consegue rodar npm, a CLI elimina bastante boilerplate: autenticação, JSON, idempotência e confirmação de exclusão já vêm resolvidas. Recorra a HTTP puro só quando não há shell.

  • A chave vive no ambiente, não no prompt

    Coloque FIRSTSALES_API_KEY no cofre de secrets do Codex e referencie-a. Uma chave no prompt acaba nos logs e no histórico.

  • whoami é a verificação de segurança mais barata

    Uma chamada confirma que o Codex está apontando para a org e o workspace certos antes de escrever qualquer coisa. Pulá-la é como dados acabam no workspace errado.

  • Idempotency-Key em toda criação

    Agentes autônomos repetem chamadas. Uma chave de idempotência estável transforma um POST repetido em um no-op em vez de um contato duplicado ou uma cobrança dobrada.

Perguntas frequentes

O Codex deve usar a CLI ou a API?

Se o Codex tem acesso a shell com npm, use a CLI. Se ele roda em um navegador ou em um sandbox sem shell, chame a Developer API via HTTPS. O caminho da API é o padrão para agentes baseados em navegador.

Como dou a chave ao Codex com segurança?

Guarde-a como FIRSTSALES_API_KEY no ambiente/cofre de secrets do Codex e referencie a variável no código. Não cole a chave crua em prompts nem a commite.

Qual é a URL base e a primeira chamada?

Base https://api.app.firstsales.io, autenticação Bearer. Primeira chamada GET /api/v1/whoami para confirmar o contexto de org e workspace antes de qualquer escrita.

Como evito escritas duplicadas em retentativas?

Envie um header Idempotency-Key nas requisições de criação. Uma repetição com a mesma chave retorna o resultado original em vez de criar um segundo registro.

O que o Codex nunca deve fazer?

Nunca chamar rotas privadas do app, callbacks de provedores, pixels de rastreamento, handlers de descadastro ou endpoints internos de cron, e nunca raspar a interface do app. Fique na /api/v1 pública; pare e reporte 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.

$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.