Aller au contenu
NouveauDécouvrir comment

Utiliser FirstSales avec Gemini

Reliez Gemini à FirstSales via l'API REST avec des outils fonctionnels restreints — lecture avant écriture, portées par outil et mutations sûres et vérifiables.

Tutoriels
Développeur & CLI
min de lecture
8 min
étapes
6 · Avancé

  1. Deux façons de connecter Gemini

    Si votre environnement Gemini (par exemple la CLI Gemini avec accès shell) peut exécuter npm, installez @firstsales.io/cli et exposez-la comme outil : elle gère l'authentification, le JSON et l'idempotence. Si Gemini fonctionne uniquement via API, appelez la Developer API de FirstSales en HTTPS depuis vos implémentations de fonction/outil. La documentation classe Gemini par défaut parmi les agents API-first.

  2. Stockez la clé en dehors du modèle

    Créez une clé Developer API dans Settings → API et conservez-la dans la configuration côté serveur de votre application sous FIRSTSALES_API_KEY. Gemini doit appeler un tool/function qui lit la clé côté serveur : le modèle lui-même ne doit jamais voir ni émettre la clé brute.

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

  3. Définissez des outils restreints, pas une échappatoire HTTP brute

    Donnez à Gemini un petit ensemble de fonctions dédiées (whoami, list_contacts, create_contact, campaign_analytics) chacune correspondant à un seul endpoint public. Cela maintient le modèle sur la surface prise en charge au lieu de le laisser construire des URL arbitraires.

    # what each tool calls under the hood
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. Vérifiez l'identité dès le premier appel d'outil

    Demandez à l'agent d'appeler whoami avant toute écriture afin qu'il confirme le contexte de l'org et du workspace :

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

  5. Écrivez de façon idempotente depuis votre outil de création

    Votre outil create_contact doit toujours attacher un Idempotency-Key afin qu'un appel de fonction rejoué ne puisse pas créer un doublon :

    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. Gérez les erreurs et restez sur la surface publique

    Dans chaque outil, gérez le 401 (clé invalide/révoquée), le 422 (validation (remontez le champ concerné) et le 429 (patientez, puis réessayez). Sur unsupported_operation, renvoyez la limitation au modèle et arrêtez-vous) ne laissez jamais Gemini scraper l'application ou accéder à des routes privées, des callbacks, des pixels ou des endpoints cron.

Astuces de pro

  • Encapsulez les endpoints en outils restreints

    Ne donnez pas à Gemini une fonction générique « appeler n'importe quelle URL ». Des outils dédiés (create_contact, campaign_analytics) maintiennent le modèle sur la surface publique et rendent ses actions auditables.

  • Le modèle ne touche jamais la clé

    Lisez FIRSTSALES_API_KEY côté serveur, à l'intérieur de l'outil. Si la clé peut apparaître dans le contexte ou la sortie du modèle, elle peut fuiter dans les logs.

  • whoami comme premier appel de fonction

    Faites de la vérification d'identité le tout premier geste, afin que Gemini confirme toujours l'org/le workspace avant d'écrire.

  • Shell disponible ? La CLI demande moins de code

    Si la CLI Gemini dispose d'un shell et de npm, appeler firstsales en ligne de commande est plus simple que de coder des outils HTTP à la main : l'authentification, le JSON, l'idempotence et la confirmation de suppression sont inclus.

Questions fréquentes

Gemini utilise-t-il la CLI ou l'API ?

Par défaut la Developer API, encapsulée sous forme de fonctions/outils. Si votre environnement Gemini dispose d'un accès shell avec npm, la CLI est une alternative demandant moins d'effort, qui gère l'authentification et l'idempotence pour vous.

Comment garder la clé à l'écart du modèle ?

Stockez FIRSTSALES_API_KEY dans la configuration côté serveur et lisez-la à l'intérieur de l'implémentation de l'outil. Le modèle appelle l'outil ; il ne voit ni n'émet jamais la clé brute.

Comment structurer les outils ?

Sous forme de fonctions restreintes, à usage unique : une par endpoint public (whoami, liste/création de contact, campaign analytics). Évitez un outil générique « récupérer n'importe quelle URL » qui laisserait le modèle sortir de la surface prise en charge.

Comment éviter les écritures en double ?

Attachez un en-tête Idempotency-Key à l'intérieur de votre outil de création. Un appel de fonction rejoué avec la même clé renvoie le résultat original au lieu de créer un doublon.

Qu'est-ce qui est interdit ?

Les routes privées de l'application, les callbacks des fournisseurs, les pixels de suivi, les gestionnaires de désabonnement, les endpoints cron internes, et le scraping de l'interface. Restez sur /api/v1 public ; arrêtez-vous sur unsupported_operation.

Développeur & CLI

Une prospection qui continue quand vous vous déconnectez.Leads, emails, relances et réponses, gérés.

Connectez des boîtes illimitées et laissez les agents IA trouver les leads, écrire chaque email et relancer. Ou envoyez vos propres modèles en mode manuel. À partir de $29/mois.

Démarrez votre essai à $1 Voir les tarifs

$1 pour 3 jours · Annulez quand vous voulez · Sans engagement

Installer avec l'IA

Votre agent de code installe la CLI et les skills FirstSales pour vous.

Prompt pour 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 ↗