> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Messages sortants et modèles ## Présentation Un agent ne peut envoyer des messages WhatsApp au format libre que dans une conversation active. Pour contacter un utilisateur en premier, notamment pour des notifications, une relance ou des appels planifiés, envoyez un **modèle de message** approuvé par Meta. Cette page explique comment créer des modèles, envoyer des messages et appels sortants, et les gérer à grande échelle. ## Créer des modèles dans WhatsApp Manager Les modèles sont créés et approuvés dans [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates), et non dans ElevenLabs. Lors de la création d'un modèle : * Choisissez une catégorie : **Utilitaire** pour les messages transactionnels, **Marketing** pour les messages promotionnels ou **Authentification** pour les codes de vérification. Meta applique une tarification et des limites de débit différentes à chaque catégorie, consultez la [tarification WhatsApp](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing). * Choisissez un format de paramètres : positionnel (`{{1}}`, `{{2}}`) ou nommé (`{{customer_name}}`). Les paramètres nommés nécessitent un `parameter_name` pour chaque valeur envoyée. * Soumettez le modèle pour approbation. L'approbation prend généralement de quelques minutes à quelques heures. Un modèle en attente ou rejeté ne peut pas être envoyé, l'API accepte la requête, mais Meta ne remet jamais le message. > **Note** > > Meta limite le nombre de [modèles marketing](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits) > qu'un même utilisateur peut recevoir sur une période donnée. Si un modèle marketing n'est pas remis sans explication, > cette limite en est souvent la cause (erreur Meta 131049). ## Envoyer un message sortant L'envoi d'un message de modèle démarre une nouvelle conversation. L'agent reste silencieux jusqu'à ce que l'utilisateur réponde, le modèle constitue le premier message, et aucun minuteur de conversation ne démarre avant la réponse de l'utilisateur. #### Dashboard Accédez à la [page WhatsApp](https://elevenlabs.io/app/agents/whatsapp), sélectionnez votre compte, puis cliquez sur le bouton ***Sortant -> Message***. Sélectionnez un agent, indiquez un ID utilisateur WhatsApp, puis choisissez le modèle de message et ses paramètres : ![Boîte de dialogue des messages WhatsApp sortants](/docs/_fern-img/13913c2ccc1d92cb59e7332b6fdb4a8c8c64760a334d1a311fa2007831eeb986.webp) #### Python ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.whatsapp.outbound_message( whatsapp_phone_number_id="524029457612345", whatsapp_user_id="12213231492", template_name="welcome", template_language_code="en", template_params=[ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "name", "text": "Daniele", } ], } ], agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversation_initiation_client_data={ "dynamic_variables": {"customer_name": "Daniele"}, }, ) ``` #### TypeScript ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.whatsapp.outboundMessage({ whatsappPhoneNumberId: "524029457612345", whatsappUserId: "12213231492", templateName: "welcome", templateLanguageCode: "en", templateParams: [ { type: "body", parameters: [ { type: "text", parameterName: "name", text: "Daniele", }, ], }, ], agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversationInitiationClientData: { dynamicVariables: { customer_name: "Daniele" }, }, }); ``` #### cURL ```bash curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "whatsapp_phone_number_id": "524029457612345", "whatsapp_user_id": "12213231492", "template_name": "welcome", "template_language_code": "en", "template_params": [ { "type": "body", "parameters": [ {"type": "text", "parameter_name": "name", "text": "Daniele"} ] } ], "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", "conversation_initiation_client_data": { "dynamic_variables": {"customer_name": "Daniele"} } }' ``` Consultez le [Guide de l'API](/docs/fr/api-reference/whats-app/outbound-message) pour le schéma complet de la requête. > **Tip** > > Un assistant IA peut adapter ces exemples à votre modèle. Indiquez-lui la documentation ElevenLabs > [llms.txt](/docs/fr/llms.txt) (ou le fichier plus détaillé [llms-full.txt](/docs/fr/llms-full.txt)), collez la > définition de votre modèle depuis WhatsApp Manager et demandez-lui la requête, il produira une commande cURL > ou un appel SDK avec les `template_params` adaptés à votre modèle. ### Paramètres de modèle `template_params` est une liste d'objets **composant**, un pour chaque composant de modèle qui contient des paramètres : * `{"type": "body", "parameters": [...]}` pour les espaces réservés du corps * `{"type": "header", "parameters": [...]}` pour un en-tête paramétré (texte, image, document ou emplacement) * `{"type": "button", "sub_type": ..., "index": ..., "parameters": [...]}` pour les paramètres de bouton Chaque entrée de `parameters` est un objet de valeur tel que `{"type": "text", "text": "Daniele"}`. Pour les modèles avec paramètres nommés, incluez `parameter_name` dans chaque valeur. L'omission de l'encapsuleur de composant, par exemple en transmettant directement `{"type": "text", ...}` dans `template_params`, est refusée. ### Format du numéro du destinataire `whatsapp_user_id` doit contenir uniquement des chiffres : l'indicatif pays suivi du numéro, sans `+`, espaces ni tirets. Par exemple, `14155552671`, et non `+1 (415) 555-2671`. > **Warning** > > Dans certains pays, l'ID WhatsApp utilisé pour une personne diffère de son numéro composé, par > exemple, les numéros mexicains comportent un `1` supplémentaire après l'indicatif pays (`521...`), et les > numéros brésiliens peuvent inclure ou omettre un neuvième chiffre. Si l'utilisateur vous a déjà envoyé un message, utilisez de préférence le > `whatsapp_user_id` de cette conversation précédente, que vous pouvez copier depuis l'historique > des conversations. ### Variables dynamiques, branches et environnements Le champ `conversation_initiation_client_data` vous permet de définir des [variables dynamiques](/docs/fr/eleven-agents/customization/personalization/dynamic-variables) pour la conversation et de l'associer à une [branche d'agent](/docs/fr/eleven-agents/operate/versioning) et à un [environnement](/docs/fr/eleven-agents/integrate/environment-variables) spécifiques : ```json { "dynamic_variables": { "customer_name": "Daniele" }, "branch_id": "agtbrch_8721kwarbs83e233mg1fzkaf9pg0", "environment": "staging" } ``` Ces paramètres persistent pour la conversation : lorsque l'utilisateur répond, l'agent reprend sur la branche et dans l'environnement demandés. La branche et l'environnement sont d'abord validés, si l'un des deux n'existe pas, la requête échoue avec une erreur et aucun message n'est envoyé. Ce champ de requête permet aux conversations sortantes de recevoir des variables dynamiques ; les conversations entrantes les reçoivent plutôt depuis un webhook d'initiation de conversation, consultez le [contexte d'initialisation](/docs/fr/eleven-agents/whatsapp#initialization-context). > **Note** > > Les paramètres de modèle remplissent uniquement le texte du modèle, ils ne sont pas accessibles à l'agent. Si l' > agent a besoin d'une valeur du modèle, comme le nom du client, transmettez-la de nouveau dans > `dynamic_variables`. ### Après l'envoi Une requête réussie renvoie un `conversation_id` et la conversation apparaît dans votre historique avec le modèle rendu comme premier message. L'agent ne s'exécute pas avant que l'utilisateur réponde. L'envoi du modèle ne démarre ni le minuteur de durée maximale ni le minuteur d'inactivité ; les deux démarrent une fois la conversation reprise. Une réponse `200` signifie qu'ElevenLabs a accepté la requête, Meta peut néanmoins refuser la remise par la suite. Si le message n'arrive jamais, consultez la section [Résolution des problèmes](/docs/fr/eleven-agents/whatsapp/troubleshooting). ## Planifier un appel sortant Les appels WhatsApp sortants nécessitent l'autorisation de l'utilisateur, consultez les [autorisations d'appel utilisateur](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions). Créez un modèle de message avec un composant de **demande d'autorisation d'appel** dans [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates). Lorsque vous planifiez un appel, ElevenLabs vérifie l'état de l'autorisation : * Autorisation déjà accordée : l'appel est lancé immédiatement. * Autorisation pas encore demandée : le modèle de demande d'autorisation est envoyé, et l'appel est lancé dès que l'utilisateur approuve. * Autorisation refusée : la conversation est enregistrée comme ayant échoué avec le motif `User declined the call permission request.` #### Dashboard Accédez à la [page WhatsApp](https://elevenlabs.io/app/agents/whatsapp), sélectionnez votre compte, puis cliquez sur le bouton ***Sortant -> Appel***. Sélectionnez un agent, indiquez un ID utilisateur WhatsApp, puis choisissez le modèle de demande d'autorisation d'appel : ![Boîte de dialogue des appels WhatsApp sortants](/docs/_fern-img/1fcf7968f1651ce8e9474e770aad4dce4e702c69b4522f5bcc65efcd8bf8a3e4.webp) #### Python ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.whatsapp.outbound_call( whatsapp_phone_number_id="524029457612345", whatsapp_user_id="12213231492", whatsapp_call_permission_request_template_name="call_permission", whatsapp_call_permission_request_template_language_code="en", agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversation_initiation_client_data={ "dynamic_variables": {"customer_name": "Daniele"}, }, ) ``` #### TypeScript ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.whatsapp.outboundCall({ whatsappPhoneNumberId: "524029457612345", whatsappUserId: "12213231492", whatsappCallPermissionRequestTemplateName: "call_permission", whatsappCallPermissionRequestTemplateLanguageCode: "en", agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversationInitiationClientData: { dynamicVariables: { customer_name: "Daniele" }, }, }); ``` #### cURL ```bash curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "whatsapp_phone_number_id": "524029457612345", "whatsapp_user_id": "12213231492", "whatsapp_call_permission_request_template_name": "call_permission", "whatsapp_call_permission_request_template_language_code": "en", "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", "conversation_initiation_client_data": { "dynamic_variables": {"customer_name": "Daniele"} } }' ``` Consultez le [Guide de l'API](/docs/fr/api-reference/whats-app/outbound-call) pour le schéma complet de la requête. Comme pour les messages sortants, `conversation_initiation_client_data` définit les variables dynamiques et associe la conversation à une branche et un environnement ; une branche ou un environnement inconnu est refusé avant la planification de l'appel. > **Note** > > Meta facture les appels sortants et les demandes d'autorisation d'appel envoyées en dehors d'une [fenêtre de service client](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows). > Ajoutez un moyen de paiement dans WhatsApp Manager avant de planifier des appels. ## Campagnes et traitement par lots Pour appeler de nombreux utilisateurs, utilisez les [appels par lots](/docs/fr/eleven-agents/phone-numbers/batch-calls) avec `whatsapp_params` : fournissez une fois l'ID du numéro de téléphone et le modèle de demande d'autorisation d'appel, ainsi qu'un `whatsapp_user_id` par destinataire. Il n'existe pas encore de point de terminaison natif de traitement par lots pour les messages sortants. Pour les campagnes de modèles, appelez le [point de terminaison des messages sortants](/docs/fr/api-reference/whats-app/outbound-message) une fois par destinataire et respectez les limites de messagerie de Meta pour votre numéro, consultez les [limites de messagerie](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/messaging-limits).