Campagnes Salesforce ↔ Alvio

Alvio fournit un contrat OpenAPI 3.0 (opens in a new tab) pour deux actions Salesforce External Services :

Ces actions utilisent un jeton x-api-key par campagne Alvio, émis lors de la création de sa source API/webhook. Le contrat OpenAPI décrit l'en-tête pour les autres clients ; Salesforce External Services ignore les schémas de sécurité OpenAPI. Il faut donc configurer cet en-tête dans un Named Credential Salesforce.

1. Préparer Alvio

1. Créez une campagne Alvio et activez sa source API/webhook.
2. Enregistrez l'UUID de la campagne et le jeton x-api-key, affiché une seule fois. Conservez la clé dans les credentials Salesforce, pas dans une variable Flow.
3. Faites un premier essai sur une campagne en brouillon et un Lead ou Contact de test. Une campagne simple active avec un modèle approuvé peut envoyer immédiatement ; une séquence active est traitée de manière asynchrone.

Prévoyez un Named Credential et un enregistrement External Services par campagne Alvio : chacune possède sa propre clé.

2. Enregistrer External Services dans Salesforce

1. Dans Setup, créez un External Credential avec authentification Custom et Named Principal. Ajoutez un paramètre d'authentification contenant la clé Alvio, puis donnez accès au principal via un permission set.
2. Créez un Named Credential pointant vers https://www.alvio.ai et utilisant cet External Credential. Ajoutez l'en-tête personnalisé x-api-key, dont la valeur référence le paramètre d'authentification.
3. Dans External Services, enregistrez un service depuis le fichier OpenAPI JSON (opens in a new tab). Sélectionnez le Named Credential et importez sendCampaignContact et listCampaignContactResults.

Le guide Named Credential de Salesforce (opens in a new tab) explique la combinaison de l'URL et du chemin serveur OpenAPI 3.0. Son guide d'authentification des callouts (opens in a new tab) détaille l'en-tête personnalisé. Le fichier OpenAPI utilise un serveur littéral https://www.alvio.ai pour faciliter l'import.

3. Envoyer les Campaign Members

Dans un Flow déclenché après l'enregistrement de CampaignMember, placez l'action sendCampaignContact sur le chemin asynchrone. Salesforce n'autorise pas l'appel externe pendant le chemin synchrone d'enregistrement. Sélectionnez les membres avec un numéro utilisable et les permissions de contact nécessaires. Associez les champs ainsi :

L'ID du Lead ou Contact, combiné au numéro, sert à reconnaître un contact renvoyé vers la même campagne Alvio. Appelez sendCampaignContact pour chaque membre retenu. Vérifiez errors et skipped dans la réponse, même avec un statut HTTP 200 : success: true ne signifie pas que tous les contacts ont été traités. Voir les contraintes des Flow déclenchés par un enregistrement (opens in a new tab) pour le chemin asynchrone.

4. Reporter les résultats dans Salesforce

Programmez un Flow par campagne Alvio qui appelle listCampaignContactResults avec le même UUID et le même credential. Salesforce autorise les appels External Services sans élément Wait dans un Flow planifié qui traite un lot d'enregistrements avec la version API 63.0 ou supérieure ; sinon, ajoutez un élément Wait avant l'appel. Voir les contraintes des Flow planifiés (opens in a new tab). Commencez avec offset=0, limit=100, puis suivez next_offset jusqu'à null. À chaque nouvelle exécution, repartez de 0, car l'état d'un contact déjà présent peut évoluer. Effectuez les appels avant de mettre à jour les CampaignMembers dans une transaction. Pour les grosses campagnes, répartissez les pages sur plusieurs transactions afin de respecter les limites d'appels Salesforce.

Retrouvez le CampaignMember avec salesforce_campaign_member_id. delivery_status représente le dernier message (queued, sent, delivered, read, replied, failed, unknown ou null). contact_status, sequence_status et progress_status décrivent séparément l'exécution de la campagne. Associez ces valeurs aux statuts CampaignMember configurés dans votre organisation Salesforce. Par exemple, replied peut correspondre au statut « a répondu » ; failed peut créer une tâche de suivi ou un statut d'erreur.

L'endpoint renvoie un instantané destiné à une réconciliation planifiée. Il ne crée pas de webhook Salesforce et ne pousse pas les mises à jour automatiquement. Si salesforce_campaign_member_id est absent, utilisez crm_contact_id et l'ID de campagne Alvio pour retrouver le membre, ou traitez le cas manuellement.

Test de l'API directe

curl -X POST 'https://www.alvio.ai/api/campaigns/webhook-receiver?campaign_id=<ID_CAMPAGNE_ALVIO>' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <CLE_API_CAMPAGNE>' \
  -d '{"phone_number":"+33612345678","crm_contact_id":"00Q000000000001","salesforce_campaign_member_id":"00v000000000001"}'
 
curl 'https://www.alvio.ai/api/campaigns/<ID_CAMPAGNE_ALVIO>/contact-results?limit=100&offset=0' \
  -H 'x-api-key: <CLE_API_CAMPAGNE>'

Le guide webhook décrit l'URL Hookdeck générée et les payloads généraux.