🔑 API REST

Vue d’ensemble

L’API REST Orsay vous permet de gérer vos séquences et d’accéder à vos conversations de manière programmatique depuis votre propre serveur. Cas d’usage :

Automatiser la création de séquences depuis un VPS ou un cron
Intégrer Orsay dans votre pipeline existant (ex : Instagram → DM séquence)
Construire des automatisations personnalisées sans passer par le dashboard
Récupérer les données de conversation pour votre CRM ou vos outils d’analytique

Authentification

Toutes les requêtes API nécessitent un Bearer token avec votre clé API.

curl -X GET https://client.api.prod.orsay.ai/api/v1/sequences \
  -H "Authorization: Bearer sk_live_votre_cle_api"

Obtenir votre clé API

Allez dans Settings → API Keys dans le dashboard Orsay
Cliquez sur Generate API Key
Copiez la clé immédiatement — elle ne sera plus affichée

Votre clé API donne un accès complet aux séquences de votre organisation. Gardez-la secrète et ne l’exposez jamais dans du code côté client.

Rate Limiting

L’API est limitée à 200 requêtes par heure par organisation. Si vous dépassez cette limite, vous recevrez une réponse 429 Too Many Requests avec un header Retry-After indiquant combien de secondes attendre.

URL de base

https://client.api.prod.orsay.ai/api/v1

Endpoints

Créer un lead

POST /leads

Envoie un lead dans une séquence, exactement comme l’action « Create Lead » de Zapier ou Make, mais avec une simple clé API. L’organisation est déduite de la clé : aucun jeton OAuth à rafraîchir, donc aucune connexion qui expire au milieu d’un scénario. Corps :

{
  "first_name": "Marie",
  "last_name": "Durand",
  "phone": "+33612345678",
  "email": "marie@exemple.com",
  "sequence_id": "a1b2c3d4-...",
  "url": "https://exemple.com/formulaire"
}

Seuls first_name et phone sont obligatoires. Le téléphone doit être au format international. Si sequence_id est omis, le lead est créé sans être abonné à une séquence. Exemple :

curl -X POST https://client.api.prod.orsay.ai/api/v1/leads \
  -H "Authorization: Bearer sk_live_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Marie","phone":"+33612345678","sequence_id":"a1b2c3d4-..."}'

Réponse (202) :

{ "message": "Lead successfully processed" }

La séquence visée doit utiliser le déclencheur Contact subscribed to sequence. Un 402 signifie que l’organisation n’a pas d’abonnement actif.

Lister les agents

GET /agents

Retourne tous les agents IA de votre organisation. Réponse :

[
  {
    "id": "e5f6g7h8-...",
    "name": "Agent Commercial",
    "is_published": true
  }
]

Lister les profils

GET /profiles

Retourne tous les profils Instagram et WhatsApp connectés. Réponse :

{
  "instagram": [
    {
      "id": "12345678",
      "username": "monbusiness",
      "status": "CONNECTED"
    }
  ],
  "whatsapp": [
    {
      "id": "abcd-1234-...",
      "name": "Mon WhatsApp",
      "status": "CONNECTED"
    }
  ]
}

Lister les séquences

GET /sequences

Retourne toutes les séquences de votre organisation. Réponse :

[
  {
    "id": "a1b2c3d4-...",
    "name": "Welcome DM",
    "trigger": "INSTAGRAM_MESSAGE",
    "channel": "INSTAGRAM",
    "active": true
  }
]

Obtenir une séquence

GET /sequences/{sequence_id}

Retourne les détails complets d’une séquence. Réponse :

{
  "id": "a1b2c3d4-...",
  "name": "Welcome DM",
  "trigger": "INSTAGRAM_MESSAGE",
  "channel": "INSTAGRAM",
  "active": true,
  "type": "INBOUND",
  "agent_id": "e5f6g7h8-...",
  "profile_id": "12345",
  "inbound_response_delay": 5,
  "inbound_response_delay_unit": "MINUTES",
  "flow": [
    {
      "delay": 0,
      "delay_unit": "MINUTES",
      "content": "Bonjour ! Comment puis-je vous aider ?",
      "template_id": null,
      "action": null
    }
  ]
}

Créer une séquence

POST /sequences

Corps de la requête :

{
  "name": "Ma Nouvelle Séquence",
  "trigger": "INSTAGRAM_MESSAGE",
  "inbound_response_delay": 5,
  "inbound_response_delay_unit": "MINUTES",
  "agent_id": "e5f6g7h8-...",
  "profile_id": "12345",
  "active": false,
  "flow": [
    {
      "delay": 0,
      "delay_unit": "MINUTES",
      "followup_delays": [
        { "delay": 30, "delay_unit": "MINUTES" }
      ]
    }
  ]
}

Champs requis :

Champ	Type	Description
`name`	string	Nom de la séquence
`trigger`	string	Type de déclencheur (voir ci-dessous)

Champs optionnels :

Champ	Type	Défaut	Description
`inbound_response_delay`	int	5	Délai avant la première réponse
`inbound_response_delay_unit`	string	”MINUTES”	SECONDS, MINUTES ou HOURS
`agent_id`	string	null	ID de l’agent IA à utiliser
`profile_id`	string	null	ID du profil Instagram ou WhatsApp
`active`	bool	false	Si la séquence est active
`flow`	array	[]	Définition des étapes du flow
`filtering_agent`	string	null	ID de l’agent de filtrage
`should_continue_existing_conversations`	bool	false	Continuer les conversations existantes
`keywords`	array	null	Mots-clés déclencheurs
`target_accounts`	array	null	Comptes cibles pour le scraping
`enable_agent_on_conversation`	bool	true	Activer l’agent IA sur les conversations
`require_manual_approval`	bool	false	Approbation manuelle requise

Réponse (201) :

{
  "id": "new-sequence-uuid"
}

Modifier une séquence

PUT /sequences/{sequence_id}

Incluez uniquement les champs que vous souhaitez modifier. Corps de la requête :

{
  "name": "Nom Mis à Jour",
  "active": true,
  "inbound_response_delay": 10
}

Réponse :

{
  "id": "a1b2c3d4-...",
  "status": "updated"
}

Supprimer une séquence

DELETE /sequences/{sequence_id}

Réponse :

{
  "status": "deleted"
}

Lister les conversations

GET /conversations

Retourne les conversations de votre organisation avec des filtres optionnels. Paramètres de requête :

Paramètre	Type	Défaut	Description
`classification`	string	null	Filtrer par classification : `positive`, `negative`, `undetermined`, `engaged`
`is_active`	boolean	null	Filtrer par statut actif (`true`) ou inactif (`false`)
`since`	string	null	Date ISO 8601 — retourne uniquement les conversations mises à jour après cette date
`page_size`	int	20	Nombre de résultats par page (max 50)
`last_lead_id`	string	null	Curseur pour la pagination (utiliser `next_cursor` de la réponse précédente)

Exemple :

curl -X GET "https://client.api.prod.orsay.ai/api/v1/conversations?classification=positive&is_active=true&page_size=10" \
  -H "Authorization: Bearer sk_live_votre_cle_api"

Réponse :

{
  "conversations": [
    {
      "lead_id": "a1b2c3d4-...",
      "channel": "WHATSAPP",
      "classification": "positive",
      "is_active": true,
      "first_name": "Jean",
      "last_name": "Dupont",
      "username": null,
      "phone_number": "+33612345678",
      "latest_message_at": "2025-06-01T14:30:00+00:00",
      "latest_inbound_at": "2025-06-01T14:30:00+00:00",
      "latest_outbound_at": "2025-06-01T14:25:00+00:00"
    }
  ],
  "next_cursor": "a1b2c3d4-..."
}

Utilisez next_cursor comme paramètre last_lead_id dans les requêtes suivantes pour paginer les résultats. Quand next_cursor est null, il n’y a plus de résultats.

Obtenir les messages d’une conversation

GET /conversations/{lead_id}

Retourne l’historique complet des messages d’une conversation. Paramètres de chemin :

Paramètre	Type	Description
`lead_id`	UUID	L’ID du lead de la conversation

Exemple :

curl -X GET "https://client.api.prod.orsay.ai/api/v1/conversations/a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Authorization: Bearer sk_live_votre_cle_api"

Réponse :

{
  "lead_id": "a1b2c3d4-...",
  "channel": "WHATSAPP",
  "classification": "positive",
  "is_active": true,
  "lead": {
    "first_name": "Jean",
    "last_name": "Dupont",
    "username": null,
    "phone_number": "+33612345678"
  },
  "messages": [
    {
      "message_id": "msg-uuid-1",
      "content": "Bonjour ! Comment puis-je vous aider ?",
      "inbound": false,
      "timestamp": "2025-06-01T14:00:00+00:00",
      "status": "DELIVERED",
      "sent_by": "ai",
      "type": "CUSTOM"
    },
    {
      "message_id": "msg-uuid-2",
      "content": "Je voudrais en savoir plus sur vos services",
      "inbound": true,
      "timestamp": "2025-06-01T14:05:00+00:00",
      "status": null,
      "sent_by": null,
      "type": null
    }
  ],
  "total_messages": 2
}

Types de déclencheurs

Déclencheur	Canal	Type
`INSTAGRAM_MESSAGE`	Instagram	Inbound
`INSTAGRAM_COMMENT`	Instagram	Outbound
`INSTAGRAM_STORY_REPLY`	Instagram	Inbound
`WHATSAPP_MESSAGE`	WhatsApp	Inbound
`CONTACT_CREATED`	WhatsApp	Outbound
`CONTACT_SUBSCRIBED_TO_SEQUENCE`	WhatsApp	Outbound

Codes d’erreur

Code	Description
`401`	Clé API invalide ou manquante
`404`	Ressource non trouvée (séquence ou conversation)
`429`	Rate limit dépassé (200 req/heure)
`400`	Requête invalide (mauvais trigger, champ manquant, format de date invalide, etc.)

Exemple : Pipeline complet

import requests
import time

API_KEY = "sk_live_votre_cle"
BASE_URL = "https://client.api.prod.orsay.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Lister les séquences
sequences = requests.get(f"{BASE_URL}/sequences", headers=HEADERS).json()
print(f"{len(sequences)} séquences trouvées")

# 2. Créer une nouvelle séquence
new_seq = requests.post(f"{BASE_URL}/sequences", headers=HEADERS, json={
    "name": "Pipeline Auto DM",
    "trigger": "INSTAGRAM_MESSAGE",
    "inbound_response_delay": 2,
    "inbound_response_delay_unit": "MINUTES",
    "agent_id": "votre-agent-id",
    "profile_id": "votre-profil-instagram-id",
    "active": True,
    "flow": [
        {
            "delay": 0,
            "delay_unit": "MINUTES",
            "followup_delays": [
                {"delay": 30, "delay_unit": "MINUTES"},
                {"delay": 120, "delay_unit": "MINUTES"}
            ]
        }
    ]
}).json()
print(f"Séquence créée : {new_seq['id']}")

# 3. La modifier plus tard
time.sleep(1)  # Petit délai entre les requêtes
requests.put(f"{BASE_URL}/sequences/{new_seq['id']}", headers=HEADERS, json={
    "name": "Pipeline Auto DM v2",
    "inbound_response_delay": 5,
})

🆕 Nouveautés

📱 WhatsApp Personnel

💼 WhatsApp Business API

📸 Instagram (Inbound)

🤖 Fonctionnalités clés

📚 Ressources

Vue d’ensemble

Authentification

Obtenir votre clé API

Rate Limiting

URL de base

Endpoints

Créer un lead

Lister les agents

Lister les profils

Lister les séquences

Obtenir une séquence

Créer une séquence

Modifier une séquence

Supprimer une séquence

Lister les conversations

Obtenir les messages d’une conversation

Types de déclencheurs

Codes d’erreur

Exemple : Pipeline complet

​Vue d’ensemble

​Authentification

​Obtenir votre clé API

​Rate Limiting

​URL de base

​Endpoints

​Créer un lead

​Lister les agents

​Lister les profils

​Lister les séquences

​Obtenir une séquence

​Créer une séquence

​Modifier une séquence

​Supprimer une séquence

​Lister les conversations

​Obtenir les messages d’une conversation

​Types de déclencheurs

​Codes d’erreur

​Exemple : Pipeline complet

Vue d’ensemble

Authentification

Obtenir votre clé API

Rate Limiting

URL de base

Endpoints

Créer un lead

Lister les agents

Lister les profils

Lister les séquences

Obtenir une séquence

Créer une séquence

Modifier une séquence

Supprimer une séquence

Lister les conversations

Obtenir les messages d’une conversation

Types de déclencheurs

Codes d’erreur

Exemple : Pipeline complet