# Accès à l'API

Une API (interface de programmation d'application) est un moyen pour différents systèmes logiciels de communiquer entre eux. L'API <span data-t="appName">Your AI Connector</span> vous permet (ou permet à votre développeur) de créer automatiquement des contacts, d'envoyer des messages, de gérer des listes et de recevoir des messages entrants depuis des canaux personnalisés — le tout sans utiliser le tableau de bord.


**Pourquoi utiliser l'API ?** Si vous souhaitez connecter l'application à un outil qui ne dispose pas d'une intégration native, ou si vous avez besoin d'automatiser des tâches répétitives à grande échelle, l'API est la solution.

::: note
**Remarque :** Cette page est de nature plus technique. Si vous êtes propriétaire d'une entreprise et non développeur, vous souhaiterez peut-être partager cette page avec votre équipe technique ou un développeur indépendant.
:::


---

## Génération de votre clé API

::: note
**Remarque :** L'accès à l'API est une fonctionnalité payante disponible sur les plans éligibles. Si votre plan ne l'inclut pas, les requêtes API seront rejetées avec une réponse `403`. Vérifiez votre plan ou contactez le support si vous n'êtes pas sûr que l'accès à l'API soit activé.
:::


1. Dans la barre latérale gauche, cliquez sur **Paramètres** (icône d'engrenage).
2. Dans la barre latérale des paramètres, sous le groupe **Intégrations**, cliquez sur **Clé API**.


3. Si vous n'avez pas encore de clé, cliquez sur **Générer une clé API**.
4. Si vous en avez déjà une, elle s'affiche masquée sous **Votre clé**. Si votre clé le permet, cliquez sur **Afficher** pour la révéler, puis sur **Copier** pour la copier — une notification de confirmation apparaîtra.
5. Conservez la clé dans un endroit sûr — vous en aurez besoin pour chaque requête API.


::: note
**Remarque :** Certains comptes affichent « Votre clé ne peut pas être affichée » au lieu d'une commande Afficher/Copier — cela se produit pour les clés créées avant que l'application ne puisse les réafficher. La clé fonctionne toujours normalement ; vous n'avez besoin de **Régénérer** (sous la carte de clé, dans la même section) que si vous avez réellement besoin de voir le texte en clair à nouveau. La régénération invalide immédiatement l'ancienne clé et interrompt toutes les intégrations qui l'utilisent jusqu'à ce que vous y colliez la nouvelle — mettez à jour vos intégrations juste après.
:::


::: warning
**Important :** Votre clé API est comme un mot de passe — elle accorde un accès complet à votre compte. Ne la partagez pas publiquement et ne la publiez nulle part où d'autres pourraient la voir. Si vous pensez que votre clé a été compromise, régénérez-la immédiatement.
:::


> **Membres de l'équipe :** la clé API appartient au propriétaire du compte. Si vous êtes connecté en tant que membre d'équipe invité (y compris en tant qu'administrateur), la section affiche une note au lieu de la clé. Connectez-vous en tant que propriétaire du compte pour l'afficher, la copier ou la régénérer — cela s'applique également aux clés délimitées.

> **Où la trouver :** **Clé API** est une section à part entière sous Paramètres → Intégrations, distincte des **Webhooks**. Si un guide ou un collègue vous dit de chercher la clé sous "Webhooks", regardez plutôt dans la section juste à côté.

---

## URL de base

Toutes les requêtes API utilisent l'adresse web de base suivante :

```
https://api.youraiconnector.com/v1/
```

---

## Authentification

Chaque requête doit inclure votre clé API afin que la plateforme sache qu'il s'agit de vous. Le moyen le plus simple consiste à l'ajouter à la fin de l'adresse web :

```
https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
```

Vous pouvez également envoyer la clé dans l'en-tête de la requête plutôt que dans l'URL (recommandé pour la production, afin que la clé ne se retrouve pas dans les journaux du serveur) :

```
X-API-Key: YOUR_API_KEY
```
```
Authorization: Bearer YOUR_API_KEY
```

Toutes les requêtes doivent utiliser une connexion sécurisée (HTTPS). Les requêtes non sécurisées (HTTP) sont rejetées.

> **Vous recherchez les guides complets pour développeurs ?** Cette page est une introduction rapide couvrant les opérations les plus courantes. Pour des guides complets étape par étape — chaque ressource, avec des exemples en cURL, JavaScript et Python — consultez [Démarrer avec l'API](../api/getting-started.md) et la [Référence de l'API](../api/reference.md).

---

## Opérations API courantes

### Créer un contact

**Requête :**

```http
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}
```

**Champs requis :** un `phoneNumber` (avec code pays) est toujours requis pour créer un contact. Une adresse e-mail seule ne suffit pas — une requête sans numéro de téléphone valide est rejetée. L'e-mail est facultatif.

**Réponse :**

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

Enregistrez `data.contactId` — vous en aurez besoin pour l'appel "Ajouter un contact à une liste".

::: note
**Remarque :** si un contact avec le même numéro de téléphone existe déjà, l'API ne crée pas et ne renvoie pas ce contact — elle renvoie `{ "success": false, "error_code": 409 }`. Recherchez d'abord le contact existant avec `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...`.
:::


---

### Ajouter un contact à une liste

```http
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}
```

Trouvez l'ID d'une liste dans l'application sous **Contacts → Listes**, via le menu de la ligne de la liste (**Copier l'ID de la liste**).

---

### Mettre à jour un contact

```http
PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}
```

Seuls les champs que vous incluez sont modifiés. C'est également la méthode pour charger en masse des valeurs de champs personnalisés après une importation — consultez [Champs personnalisés, profil de prospect et notes](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). Détails complets dans l'[API Contacts](../api/contacts.md).

---

### Envoyer un message (Canal personnalisé)

```http
POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}
```

| Champ | Requis | Description |
|---|---|---|
| `customData.fromId` | Oui | L'ID du contact sur votre plateforme |
| `customData.customChannel` | Oui | Le nom de votre canal personnalisé |
| `customData.body` | Oui | Le texte du message à envoyer |
| `customData.campaignId` | Non | Acheminer le message vers une campagne spécifique |
| `customData.firstName` | Non | Prénom du contact (utilisé lors de la création d'un nouveau contact) |
| `customData.lastName` | Non | Nom de famille du contact |
| `customData.email` | Non | Adresse e-mail du contact |

::: note
**Remarque :** ce point de terminaison est destiné à la messagerie via canal personnalisé. Pour WhatsApp, SMS, Instagram et Messenger, les messages sont envoyés via les diffusions, les campagnes et les agents IA.
:::


---

### Recevoir des messages entrants (Canal personnalisé)

Acceptez des messages provenant de systèmes externes en tant que canal personnalisé. C'est ainsi que des intégrations comme GoHighLevel envoient des messages dans <span data-t="appName">Your AI Connector</span>. Consultez les [Canaux personnalisés](../messaging-channels/custom-channels.md) pour plus de détails.

```http
POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}
```

| Champ | Requis | Description |
|---|---|---|
| `customData.messageSid` | Oui | Un identifiant unique pour ce message (évite les doublons). Vous pouvez également utiliser `customData.id`. |
| `customData.fromId` | Oui | L'identifiant de l'expéditeur dans votre système externe. |
| `customData.toId` | Oui | Votre identifiant d'entreprise. |
| `customData.body` | Oui | Le texte du message. |
| `customData.channel` | Non | Une étiquette pour la source (par ex. `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | Non | Statut du message. Par défaut `"received"`. |
| `messageType` | Non | `"text"` pour les messages texte, `"reaction"` pour les réactions par émoji. |

---

## Aperçu des opérations disponibles

| Action | Méthode | Adresse | Description |
|---|---|---|---|
| Créer un contact | `POST` | `/contacts` | Ajouter un nouveau contact à votre compte |
| Obtenir les détails d'un contact | `GET` | `/contacts?phoneNumber=X` ou `/contacts?email=X` | Rechercher un contact par numéro de téléphone ou e-mail |
| Mettre à jour un contact | `PUT` | `/contacts/{contactId}` | Mettre à jour n'importe quel champ sur un contact existant |
| Ajouter un contact à une liste | `POST` | `/contacts/lists` | Ajouter un contact existant à une liste spécifique |
| Envoyer un message | `POST` | `/send_custom_channel_message` | Envoyer un message via un canal personnalisé |
| Recevoir un message | `POST` | `/incoming_custom_channel_message` | Accepter un message provenant d'un système externe |

---

## Limitation du débit (Rate Limiting)

The API enforces rate limits to ensure platform stability. Exceeding your limit returns `429 Too Many Requests` — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in [import feature](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) for guidance.

---

## Bonnes pratiques

- **Stockez votre clé API en toute sécurité** — utilisez un gestionnaire de mots de passe ou une configuration côté serveur, jamais de code côté client qu'un visiteur du navigateur pourrait lire.
- **Incluez toujours l'indicatif pays** dans les numéros de téléphone (`+1` pour les États-Unis, `+44` pour le Royaume-Uni, `+31` pour les Pays-Bas).
- **Gérez les erreurs avec élégance** — vérifiez les codes de statut et lisez les messages d'erreur renvoyés.
- **Gérez les doublons** — un numéro de téléphone en double renvoie `{ "success": false, "error_code": 409 }` au lieu d'un nouveau contact. Recherchez d'abord le contact si vous devez travailler avec lui.
- **Testez avec un petit jeu de données** avant d'effectuer des opérations en masse.

---

## Réponses d'erreur

```json
{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}
```

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

## Étapes suivantes

- [Webhooks](webhooks.md) — recevez des notifications en temps réel de l'application (une section distincte de votre clé API).
- [Connecter des assistants IA (MCP)](connect-ai-clients.md) — utilisez la même clé API pour laisser Claude piloter votre compte.
- [Formulaires de prospects Facebook](facebook-lead-forms.md) — utilisez l'API avec des plateformes d'automatisation pour capturer des prospects.
- [Intégration GoHighLevel](ghl-integration.md) — un exemple complet d'intégration API bidirectionnelle.