En-têtes SIP

La source d'init SIP header lit une information transportée dans le message INVITE de l'appel vers une variable d'init. Les valeurs sont lues à l'établissement de l'appel, avant l'exécution du nœud Welcome : elles sont donc disponibles dès le message d'accueil.

Les six en-têtes supportés

Six en-têtes sont transportés de bout en bout, de l'INVITE de l'opérateur jusqu'à votre agent. Leurs noms sont fixes ; seul leur contenu est défini entre vous et votre opérateur. Tout autre en-tête, standard ou personnalisé, n'atteint jamais la plateforme.

Cas d'usage typiques : un identifiant client issu de votre CRM ou d'un SVI en amont, un numéro de dossier ou de commande, un code campagne, un niveau de service, une langue préférée. Convenez avec votre opérateur de quel en-tête transporte quelle valeur : aucun autre en-tête n'étant livrable, la correspondance entre valeurs et en-têtes est une convention entre vous et lui.

X-MAI-User-to-User

L'en-tête User-to-User (UUI, RFC 7433) permet au RTC de transporter une donnée applicative de bout en bout, généralement héritée d'un champ UUI RNIS. Pour un appel arrivant du RTC, il transporte le plus souvent un identifiant CRM posé par un SVI ou un centre de contact en amont ; X-MAI-User-to-User est l'emplacement conventionnel pour livrer cette valeur à Manivox.

La valeur est transmise telle que reçue, sans décodage ni normalisation. En pratique le contenu UUI est le plus souvent encodé en hexadécimal et accompagné de ses paramètres :

X-MAI-User-to-User: 34373131383239;encoding=hex;purpose=isdn-uui

C'est donc à vous, si besoin, de retirer les paramètres et de décoder la valeur dans votre flux (nœud API ou traitement back-office).

Configuration côté agent

1. Ouvrez l'éditeur d'agent, onglet Initialisation, section variables d'init.
2. Créez une variable et donnez-lui le nom de votre choix (par ex. crm_id). C'est ce nom que vous utiliserez dans vos nœuds.
3. Choisissez la source SIP header.
4. Sélectionnez l'en-tête à lire dans la liste déroulante : X-MAI-Custom1 … X-MAI-Custom5 ou X-MAI-User-to-User.

Chaque en-tête peut être mappé sur une variable. Le même en-tête peut alimenter plusieurs variables si nécessaire. Aucune requête n'est émise : il n'y a ni URL, ni corps, ni timeout à configurer, et rien qui ralentisse l'appel.

Exemple d'INVITE

Un exemple d'INVITE tel que livré par votre opérateur ou votre trunk SIP :

INVITE sip:+33176360001@sbc.manivox.ai SIP/2.0
From: <sip:+33612345678@trunk.example.com>;tag=a1b2c3
To: <sip:+33176360001@sbc.manivox.ai>
Call-ID: 8f3c1e2a-4b7d-11f0-9c1a-0242ac120002
X-MAI-Custom1: 4711829
X-MAI-Custom2: PREMIUM
X-MAI-Custom3: summer_campaign_2026

Avec la configuration ci-dessus (en-tête X-MAI-Custom1 mappé sur la variable crm_id), l'agent dispose, dès le nœud Welcome, de :

Bonjour, vous êtes bien chez {{agent_name}}. Je vois votre dossier {{crm_id}}.

Règles de lecture

• Les en-têtes ne sont lus que sur l'INVITE initial de l'appel. Un en-tête envoyé dans un re-INVITE ou un UPDATE ultérieur n'est pas pris en compte.
• La casse des noms d'en-têtes est ignorée : que votre opérateur écrive X-MAI-Custom1 ou x-mai-custom1 sur le réseau ne change rien. Cette documentation utilise la casse canonique affichée dans l'éditeur.
• Les espaces de début et de fin sont retirés, puis la valeur est convertie vers le type déclaré de la variable (string, number, boolean, datetime). Aucune autre interprétation n'est appliquée : pas de décodage JSON, pas d'analyse de paramètres.
• Un en-tête que l'opérateur n'a pas envoyé, ou envoyé vide, laisse la variable à sa valeur par défaut déclarée, plutôt que de l'écraser : un flux continue donc de fonctionner quand la métadonnée n'est présente que sur une partie des appels. Prévoyez quand même le cas absent (nœud condition, formulation neutre du message d'accueil).
• Si le même en-tête est présent plusieurs fois dans l'INVITE, une seule valeur est conservée.
• Les valeurs d'en-têtes doivent être en UTF-8 si elles contiennent des caractères accentués. SIP est en UTF-8 par défaut, mais certains opérateurs envoient de l'ISO-8859-1 / Latin-1. Une valeur qui n'est pas de l'UTF-8 valide est écartée (avec un avertissement dans les logs de la plateforme) plutôt que de corrompre les autres en-têtes de l'appel : demandez de l'UTF-8 à votre opérateur, ou limitez-vous à de l'ASCII.
• Longueur maximale recommandée : 256 caractères par en-tête. Au-delà, la valeur peut être tronquée par des équipements intermédiaires.

Sécurité et confidentialité

Le contenu des en-têtes SIP n'est ni authentifié ni signé : il est déclaratif. Avec le transport TLS, il est chiffré entre votre équipement et notre SBC ; en SIP sur UDP, il circule en clair sur le réseau. Dans les deux cas :

• N'y placez jamais de donnée sensible (mot de passe, numéro de carte bancaire, donnée de santé).
• Préférez des identifiants opaques (par ex. un identifiant CRM) à des données personnelles en clair.
• Ne fondez pas une décision critique (authentification, accès à un dossier) sur la seule valeur d'un en-tête : validez-la auprès de votre système avec un nœud API. Cela vaut aussi pour X-MAI-User-to-User, dont le contenu provient d'un tiers en amont du réseau.

Combiner avec un appel API

Les deux mécanismes sont complémentaires. Un schéma courant consiste à recevoir un identifiant dans X-MAI-Custom1 (ou dans X-MAI-User-to-User pour une arrivée RTC), puis à l'utiliser dans une variable d'init avec la source HTTP Request pour récupérer le contexte complet du client avant le nœud Welcome.

Vérifier la transmission

Si la variable reste vide alors que l'information devrait être présente :

1. Vérifiez quel en-tête est sélectionné dans le mapping : la liste déroulante ne propose que les six en-têtes supportés, une valeur envoyée par votre opérateur dans tout autre en-tête ne peut donc jamais arriver.
2. Vérifiez auprès de votre opérateur que la valeur est bien émise dans l'en-tête X-MAI-* convenu, et qu'aucun équipement intermédiaire ne la retire : c'est la cause la plus fréquente.
3. Si le contenu comporte des caractères accentués, cherchez dans les logs de la plateforme une valeur écartée pour encodage non-UTF-8.
4. Inspectez la valeur reçue sur la page de détail de l'appel, où les en-têtes sont affichés à côté des autres variables d'init. Les en-têtes reçus sont aussi renvoyés par l'API calls (champ sip_headers), utile pour confirmer ce que l'opérateur envoie réellement avant de mapper quoi que ce soit.