Documentation API publique

Ajoutez un contact. VoxSatisfy orchestre le reste.

Cette documentation couvre les capacités déjà exposées: authentification HMAC, ingestion de contacts, dispatch Trigger.dev prioritaire et compatibilité legacy.

Voir l’endpoint Gérer les clés

API contact ingestion

POST/v1/campaigns/{campaignId}/contacts

Payload

signé HMAC

external_id"crm-contact-789"CRM

phone_e164"+33612345678"E.164

consenttruerequis

202 Accepted

Le contact est accepté et la queue prend le relais.

Priorité

Résultat

UI native

Clés API utilisateur

Création, révocation, régénération et suivi depuis Paramètres > Intégrations.

Signature HMAC

Chaque appel signé avec timestamp anti-replay et secret chiffré côté serveur.

Ingestion de contacts

Ajout progressif de contacts à une campagne existante pendant sa période de collecte.

Dispatch prioritaire

Déclenchement Trigger.dev en priorité 60, sans attendre la fin de l’appel.

Authentification

Une clé visible, un secret jamais réaffiché.

Les clés se créent depuis l’espace connecté. Le client signe le body brut avec son secret; Vox vérifie la signature, l’expiration et la fenêtre anti-replay.

x-api-key: clé publique préfixée vox_

x-timestamp: date ISO dans une fenêtre de 5 minutes

x-signature: HMAC SHA-256 en hexadécimal

Signature Node.js

const crypto = require('crypto')

const payload = {
  external_id: 'crm-contact-789',
  phone_e164: '+33612345678',
  consent: true,
}

const rawBody = JSON.stringify(payload)
const timestamp = new Date().toISOString()
const dataToSign = `${timestamp}.${rawBody}`
const signature = crypto
  .createHmac('sha256', apiSecret)
  .update(dataToSign)
  .digest('hex')

Endpoint public

Ajouter un contact à une campagne.

POST/v1/campaigns/{campaignId}/contacts

POST contact — curl

curl -X POST "https://voxsatisfy.com/v1/campaigns/123/contacts" \
  -H "content-type: application/json" \
  -H "x-api-key: vox_xxxxxxxxxxxxxxxxxxxx" \
  -H "x-timestamp: 2026-06-14T12:00:00.000Z" \
  -H "x-signature: 8f6d...d2a1" \
  -d '{
    "external_id": "crm-contact-789",
    "phone_e164": "+33612345678",
    "email": "client@example.com",
    "first_name": "Jean",
    "last_name": "Dupont",
    "consent": true
  }'

`external_id` vient de votre système.

Utilisez l’identifiant stable de votre CRM, outil support, ERP ou base interne. VoxSatisfy s’en sert pour reconnaître le même contact lors des prochains envois.

Champs acceptés par la route canonique

La campagne est portée par l’URL. Le body contient uniquement les informations du contact à injecter.

9 champs

campaignId

Obligatoire

URL

number

Identifiant de la campagne VoxSatisfy qui doit recevoir le contact.

Exemple

123

external_id

Optionnel

body

string

Identifiant du contact dans votre CRM, ERP, outil support ou base interne. Recommandé pour éviter les doublons.

Exemple

crm-contact-789

phone_e164

Obligatoire

body

string

Numéro de téléphone au format E.164. C’est le champ utilisé pour déclencher l’appel ou le SMS.

Exemple

+33612345678

email

Optionnel

body

string

Adresse email du contact, conservée dans sa fiche pour enrichir le contexte.

Exemple

client@example.com

first_name

Optionnel

body

string

Prénom du contact, utilisé pour personnaliser les échanges et les vues UI.

Exemple

Jean

last_name

Optionnel

body

string

Nom du contact, visible dans les listes et les statistiques de campagne.

Exemple

Dupont

gender

Optionnel

body

string

Champ libre de segmentation si votre outil source transmet cette information.

Exemple

male

consent

Obligatoire

body

boolean

Doit être true sur la route canonique. Vox refuse l’ingestion sans consentement explicite.

Exemple

true

opt_in

Optionnel

body

boolean

Vaut true par défaut. Si false, Vox considère le contact comme opposé et refuse le traitement.

Exemple

true

202 Accepted

{
  "success": true,
  "data": {
    "contact": {
      "id": 123,
      "external_id": "crm-contact-789"
    },
    "campaign_run": {
      "id": 456,
      "status": "pending"
    },
    "dispatch": {
      "queued": true,
      "trigger_run_id": "run_xxx",
      "priority": 60
    }
  }
}

Consentement

La route canonique exige consent: true.

Idempotence

external_id évite les doublons sur la liste de campagne.

Déclenchement

La réponse arrive dès que la queue est acceptée.

Pipeline

De la requête à l’appel, sans bloquer le client.

Étape 1

Requête signée

La signature est vérifiée avant lecture métier.

Étape 2

Campagne résolue

La clé doit appartenir au propriétaire de la campagne.

Étape 3

Contact normalisé

Téléphone E.164, consentement et idempotence par external_id.

Étape 4

Run préparé

Vox crée ou réutilise le run de campagne du contact.

Étape 5

Queue prioritaire

Trigger.dev enfile le traitement et lance le scénario.

Résultats transparents dans l’UI

Les contacts injectés par API alimentent la même campagne et les mêmes statistiques.

Aperçu des statistiques de campagne VoxSatisfy

Codes d’erreur

Des réponses stables pour automatiser vos retries.

Authentification

INVALID_API_KEYINVALID_SIGNATURETIMESTAMP_EXPIREDRATE_LIMITED

Campagne

CAMPAIGN_NOT_FOUNDCAMPAIGN_FORBIDDENCAMPAIGN_CLOSEDCOLLECTION_CLOSED

Contact

INVALID_CONTACTCONSENT_REQUIREDCONTACT_INGESTION_FAILED

Dispatch

ALREADY_IN_PROGRESSALREADY_COMPLETEDTRIGGER_DISPATCH_FAILED

Compatibilité legacy

L’ancien endpoint reste disponible.

La route historique accepte toujours la clé `CONTACTS_API_KEY`, `campaign_id` dans le body et `list_id` temporairement. Elle utilise maintenant le même service d’ingestion et déclenche aussi Trigger.dev en priorité.

POST/api/contacts

Cette route existe pour les intégrations déjà branchées. Les nouveaux clients doivent utiliser /v1/campaigns/{campaignId}/contacts.

POST legacy — curl

curl -X POST "https://voxsatisfy.com/api/contacts" \
  -H "content-type: application/json" \
  -H "x-api-key: legacy_contacts_api_key" \
  -d '{
    "campaign_id": 123,
    "list_id": 456,
    "external_id": "crm-contact-789",
    "phone_e164": "+33612345678"
  }'

Champs acceptés par la route legacy

Cette route conserve l’ancien contrat: la campagne est transmise dans le body et list_id reste accepté temporairement.

10 champs

campaign_id

Obligatoire

body

number

Identifiant de la campagne VoxSatisfy. La route legacy le reçoit dans le body.

Exemple

123

list_id

Optionnel

body

number

Accepté temporairement pour compatibilité. S’il est transmis, il doit correspondre à la liste de la campagne.

Exemple

456

external_id

Optionnel

body

string

Identifiant du contact dans votre outil interne. Recommandé pour rattacher les futurs appels au même contact.

Exemple

crm-contact-789

phone_e164

Obligatoire

body

string

Numéro de téléphone au format E.164, obligatoire pour lancer le scénario.

Exemple

+33612345678

email

Optionnel

body

string

Adresse email optionnelle pour enrichir la fiche contact.

Exemple

client@example.com

first_name

Optionnel

body

string

Prénom optionnel du contact.

Exemple

Jean

last_name

Optionnel

body

string

Nom optionnel du contact.

Exemple

Dupont

gender

Optionnel

body

string

Champ libre optionnel transmis depuis l’outil source.

Exemple

male

consent

Optionnel

body

boolean

Toléré sur la route legacy, mais non obligatoire pour conserver la compatibilité existante.

Exemple

true

opt_in

Optionnel

body

boolean

Vaut true par défaut. Si false, le contact est refusé.

Exemple

true

Hors périmètre public

Ce que la documentation ne promet pas encore.

Ces capacités existent côté produit ou pourront venir plus tard, mais elles ne sont pas exposées dans l’API publique actuelle.

Création de campagnes par API

Lecture des statistiques par API

Modification de scénarios par API

Endpoints internes de formulaire SMS

const crypto = require('crypto') const payload = { external_id: 'crm-contact-789', phone_e164: '+33612345678', consent: true, } const rawBody = JSON.stringify(payload) const timestamp = new Date().toISOString() const dataToSign = `${timestamp}.${rawBody}` const signature = crypto .createHmac('sha256', apiSecret) .update(dataToSign) .digest('hex')

curl -X POST "https://voxsatisfy.com/v1/campaigns/123/contacts" \ -H "content-type: application/json" \ -H "x-api-key: vox_xxxxxxxxxxxxxxxxxxxx" \ -H "x-timestamp: 2026-06-14T12:00:00.000Z" \ -H "x-signature: 8f6d...d2a1" \ -d '{ "external_id": "crm-contact-789", "phone_e164": "+33612345678", "email": "client@example.com", "first_name": "Jean", "last_name": "Dupont", "consent": true }'

{ "success": true, "data": { "contact": { "id": 123, "external_id": "crm-contact-789" }, "campaign_run": { "id": 456, "status": "pending" }, "dispatch": { "queued": true, "trigger_run_id": "run_xxx", "priority": 60 } } }

De la requête à l’appel, sans bloquer le client.

Étape 1

Requête signée

La signature est vérifiée avant lecture métier.

Étape 2

Campagne résolue

La clé doit appartenir au propriétaire de la campagne.

Étape 3

Contact normalisé

Téléphone E.164, consentement et idempotence par external_id.

Étape 4

Run préparé

Vox crée ou réutilise le run de campagne du contact.

Étape 5

Queue prioritaire

Trigger.dev enfile le traitement et lance le scénario.

L’ancien endpoint reste disponible.

POST/api/contacts

Cette route existe pour les intégrations déjà branchées. Les nouveaux clients doivent utiliser /v1/campaigns/{campaignId}/contacts.

curl -X POST "https://voxsatisfy.com/api/contacts" \ -H "content-type: application/json" \ -H "x-api-key: legacy_contacts_api_key" \ -d '{ "campaign_id": 123, "list_id": 456, "external_id": "crm-contact-789", "phone_e164": "+33612345678" }'