Introduction au SIP

Vonage SIP Interconnect permet l'interopérabilité entre les terminaux WebRTC et les systèmes de téléphonie existants, afin que les utilisateurs puissent passer des appels en contexte basés sur le protocole SIP, tout en naviguant simultanément sur le site web ou l'application mobile.

Vous pouvez utiliser l'API REST pour connecter votre plateforme SIP aux sessions. Cela vous permet d'ajouter l'audio (et, éventuellement, la vidéo) d'un appel SIP en tant que flux dans la session. L'audio des autres flux de la session est mélangé et envoyé à votre point d'extrémité SIP. Si vous incluez de la vidéo dans l'appel SIP, la vidéo des flux des autres participants (jusqu'à 9) est disposée en grille et envoyée en tant que flux vidéo unique à votre point d'extrémité SIP.

La fonction d'interconnexion SIP n'est prise en charge que dans les sessions acheminées (sessions qui utilisent la fonction Routeur média).

Cas d'utilisation cibles

Cas d'utilisation d'un centre de contact

Dans le cadre de leur stratégie de communication omnicanale, les entreprises s'intéressent à WebRTC pour que les utilisateurs finaux puissent.. :
- Utiliser les navigateurs ou les applications mobiles pour se connecter aux centres de contact, plutôt que d'utiliser uniquement les téléphones, afin d'offrir une expérience plus omniprésente et contextuelle.
- Utiliser la vidéo/collaboration en plus de l'audio pour améliorer l'efficacité et accroître la satisfaction et la fidélisation des clients.

RTPC Fallback

Dans certains cas, il n'est pas possible de se connecter en utilisant les clients SDK habituels :
- Si l'un des participants dispose d'un navigateur qui ne prend pas en charge WebRTC ou
- Si le pare-feu est trop restrictif
Si la connectivité sur IP/Vonage échoue pour les raisons mentionnées ci-dessus, les clients auront besoin d'un mécanisme de repli. L'interconnexion SIP permet aux clients de passer un appel téléphonique normal lors d'une session. Les clients doivent configurer une passerelle SIP-PSTN à cet effet.

Lancer un appel SIP

Pour lancer l'appel SIP, utilisez l'API REST. Envoyez une requête HTTPS POST à l'URL suivante :

/v2/project/:app-id/dial

Remplacer :app-id avec votre ID APP.

Régler le Content-Type à l'en-tête application/json. Il faut également définir un en-tête d'authentification du support, c'est-à-dire : Authorization: Bearer <token> où <token> est un JWT généré à l'aide de votre pouvoirs.

Définir le corps de la demande en données JSON au format suivant :

{
  "sessionId": "session ID",
  "token": "A valid token",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "headers": {
      "headerKey": "headerValue"
    },
    "auth": {
      "username": "username",
      "password": "password"
    },
    "secure": true|false,
    "video": true|false,
    "observeForceMute": true|false
  }
}

L'objet JSON comprend les propriétés suivantes :

sessionId (obligatoire) - L'identifiant de session de l'appel SIP à rejoindre.
token (obligatoire) - Le jeton à utiliser pour le participant appelé. Vous pouvez ajouter des données de jeton pour identifier que le participant est un point d'extrémité SIP ou pour d'autres données d'identification, telles que des numéros de téléphone. (Les bibliothèques client comprennent des propriétés permettant d'inspecter les données de connexion d'un client connecté à une session). Voir la page Création de jetons guide.
SIP uri (obligatoire) : L'URI SIP à utiliser comme destination de l'appel SIP initié depuis Vonage vers votre plateforme SIP.

Si le SIP uri contient un transport=tls la négociation entre Vonage et le point de terminaison SIP se fera de manière sécurisée. Notez que cela ne s'applique qu'à la négociation elle-même, et non à la transmission de l'audio. Si vous souhaitez que la transmission de l'audio (et de la vidéo, le cas échéant) soit également cryptée, définissez l'option secure à la propriété true.

Il s'agit d'un exemple de négociation d'appel sécurisée :

"sip:user@sip.partner.com;transport=tls"

Il s'agit d'un exemple de négociation d'appel non sécurisée :

"sip:user@sip.partner.com"

Vous pouvez également régler la transport à l'en-tête transport=tcp ou transport=udp. Le transport par défaut est udp.

SIP from (facultatif) : Le numéro ou la chaîne de caractères qui sera envoyé au numéro SIP final en tant que l'appelant. Il doit s'agir d'une chaîne de caractères de la forme from@example.comoù from peut être une chaîne de caractères ou un nombre.

Si from est fixé à un nombre (par exemple, "14155550101@example.com"), il s'affichera s'affichera comme numéro entrant sur les téléphones RTC. Si le from est indéfini ou correspond à une chaîne de caractères (par exemple, "joe@example.com"), +00000000 s'affichera comme numéro entrant sur les téléphones RTC.

Si from est indéfini, ou défini comme une chaîne de caractères (par exemple, "joe@example.com"), qui est non reconnu ou un numéro non autorisé, dans la plupart des cas, il sera converti en "Unknown" avant que la demande ne soit transmise à un opérateur pour la terminaison RTPC par les fournisseurs SIP. En fonction du fournisseur, "Unknown" apparaîtra comme le numéro entrant sur les téléphones RTPC. Dans certains cas, les fournisseurs peuvent rejeter ces appels pour des raisons de sécurité, afin d'éviter des problèmes tels que l'usurpation de numéro. d'éviter des problèmes tels que l'usurpation de numéro. Si l'appel n'est pas rejeté par le fournisseur, + s'affichera comme numéro entrant sur les téléphones RTC, +00000000 apparaîtra comme le numéro entrant sur les téléphones RTC.

Un numéro est considéré comme non reconnu lorsqu'il n'est pas E.164 ou qu'il n'est pas un Numéro virtuel Vonage si l'on se connecte à le Vonage Voice API, par exemple.

SIP headers (facultatif) - Cet objet définit les en-têtes personnalisés à ajouter au message SIP INVITE initiée par OpenTok vers votre plateforme SIP.
SIP auth (facultatif) - Cet objet contient le username et password à utiliser dans le le SIP INVITE pour l'authentification HTTP digest, si elle est requise par votre plateforme SIP.
secure (facultatif) - Indicateur booléen indiquant si le média doit être transmis crypté (true) ou non (false(par défaut).

Un appel réussi entraîne une réponse HTTP 200, avec l'identifiant de connexion et l'identifiant de flux inclus dans les données de réponse JSON :

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
  "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036",
}

video (facultatif) - Indicateur booléen qui indique si l'appel SIP comprendra de la vidéo (true) ou non (false(par défaut). Avec vidéo incluse, la vidéo du client SIP est incluse dans le flux Vonage envoyé à la session. La vidéo SIP est limitée à 480p à 800 kbps. Le client SIP recevra un flux vidéo dynamique composé des flux publiés dans la session.
observeForceMute (facultatif) - Indicateur booléen qui indique si le point d'extrémité SIP observe les règles suivantes force mute moderation (true) ou non (false(par défaut). De même, avec observeForceMute fixé à truel'appelant peut appuyer sur "*6" pour activer ou désactiver le son publié. Pour que la bascule "*6" fonctionne, l'appelant SIP DOIT négocier des DTMFs RFC2833 (chiffres RFC2833/RFC4733). Le basculement en sourdine n'est pas pris en charge avec SIP INFO ou les DTMFs en bande. Un message (en anglais) est diffusé à l'appelant lorsque celui-ci met en sourdine et rétablit la sourdine, ou lorsque le client SIP est mis en sourdine par une action de mise en sourdine forcée.
streams (facultatif) - Un tableau d'identifiants de flux à inclure dans l'appel SIP. l'appel SIP. Si vous ne définissez pas cette propriété, tous les flux de la session sont inclus dans l'appel. sont inclus dans l'appel.

Un appel réussi se traduit par une réponse HTTP 200, avec l'identifiant de connexion et l'identifiant de flux inclus dans les données de la réponse JSON. dans les données de la réponse JSON :

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
  "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036",
}

L'objet JSON comprend les propriétés suivantes :

id - Un identifiant unique pour l'appel SIP.
connectionId - L'identifiant de connexion de l'appel SIP dans la session. Vous pouvez utiliser cet identifiant de connexion pour mettre fin à l'appel SIP à l'aide de l'API REST. Voir la section suivante.

streamId - L'identifiant du flux de l'appel SIP dans la session.

La passerelle SIP envoie un message standard SIP INVITE à l'adresse que vous avez fournie dans l'appel REST. Lorsque votre point d'extrémité SIP se connecte, il est ajouté en tant que nouvelle connexion à la session, et son audio (et sa vidéo, le cas échéant) est ajouté à un nouveau flux dans la session. La nouvelle connexion est ajoutée immédiatement à la session sans attendre que le terminal SIP reçoive ou accepte l'appel. Dans les clients connectés à la session, la fonction Client SDK envoie des événements indiquant la nouvelle connexion et le nouveau flux (comme il le ferait pour d'autres connexions et flux). Les clients peuvent s'abonner au flux, comme ils le feraient pour n'importe quel autre flux de la session.

Terminer un appel SIP

L'appel se termine lorsque votre serveur SIP envoie un message BYE (pour mettre fin à l'appel). Vous pouvez également mettre fin à un appel en utilisant la méthode de l'API REST pour déconnecter un client d'une session. Utilisez l'identifiant de connexion de l'appel SIP lorsque vous appelez cette méthode. (La méthode REST pour initier le SIP renvoie l'identifiant de la connexion dans les données de la réponse).

Lorsque l'appel SIP se termine, la connexion et le flux de l'appel SIP se terminent également. Dans chaque client connecté à la session, la fonction Client SDK envoie des événements indiquant que la connexion et le flux sont terminés (de la même manière que lorsque d'autres clients se déconnectent de la session).

La passerelle SIP de Vonage met automatiquement fin à un appel après 5 minutes d'inactivité (5 minutes sans réception de média). De plus, par mesure de sécurité, la passerelle SIP de Vonage met fin à tout appel SIP qui dure plus de 6 heures.

Envoi de signaux DTMF

Vous pouvez envoyer des signaux DTMF (Dual-tone multi-frequency) aux terminaux SIP à l'aide de l'API REST. Voir Envoi de chiffres DTMF aux clients SIP.

Les événements téléphoniques sont négociés via SDP et transmis sous forme de chiffres RFC4733/RFC2833 au point d'extrémité distant.

Suivi de la progression de l'appel

Enregistrez-vous pour recevoir des rappels d'événements en temps réel pour votre appel SIP sur votre serveur d'application.

Les développeurs peuvent utiliser l'API REST de Vonage pour connecter leur plateforme SIP aux sessions. Cela vous permet d'ajouter l'audio (et la vidéo, le cas échéant) d'un appel SIP en tant que flux dans la session.

Avec la surveillance des appels SIP, les développeurs peuvent surveiller la progression de l'appel SIP, à partir de leur serveur d'application. En s'enregistrant pour les callbacks, votre URL de callback recevra des requêtes HTTP POST avec des informations sur la progression de l'appel SIP.

Enregistrement des rappels

Les informations relatives aux événements d'appel SIP peuvent être enregistrées sur des points d'extrémité HTTP au sein de votre serveur. Chaque fois qu'une activité enregistrée se produit, une requête HTTP est émise par l'infrastructure Vonage vers votre point de terminaison.

Pour enregistrer une URL de rappel :

Visitez votre Compte Video API de Vonage page.
Sélectionnez le projet pour lequel vous souhaitez enregistrer un rappel.
Définissez l'URL de rappel dans la section Surveillance SIP.

Surveillance de l'activité des appels SIP

Une fois correctement enregistrée, l'infrastructure envoie des requêtes HTTP pour tous les appels SIP d'un projet spécifique. Cela permet de suivre la progression des appels SIP et de prendre des mesures en cas d'erreur. Vous devez vous attendre à ce que

Au moins un callCreated événement par appel
Au moins un callDestroyed événement par appel
Un nombre indéfini de callUpdated événements par appel
Un nombre indéfini de muteForced événements par appel

Appel créé

Votre terminal recevra le JSON suivant pour chaque appel SIP créé :

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "applicationId":  "123456", 
  "event":  "callCreated",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

Voir Propriétés JSON ci-dessous pour les descriptions.

Appel mis à jour

Votre terminal recevra le JSON suivant lorsque l'état de chaque appel SIP sera mis à jour :

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "applicationId":  "123456",
  "event":  "callUpdated",
  "state":  "HANGUP",
  "timestamp":  1470257688309,
  "call": {
     "id":  "<conference-id>",
     "connectionId":  "<sip-ot-connection-id>",
     "createdAt":  1470257688143
  }
}

Voir Propriétés JSON ci-dessous pour les descriptions.

Appel détruit

Votre terminal recevra le JSON suivant à la fin de chaque appel SIP :

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "applicationId":  "123456",
  "event":  "callDestroyed",
  "reason_code":  "400",
  "reason_message":  "Bad Request",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

Voir Propriétés JSON ci-dessous pour les descriptions.

Sourdine forcée

Votre point d'accès recevra le JSON suivant lorsqu'un appel SIP est mis en sourdine en raison d'un événement de modération "force mute" :

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "applicationId":  "123456",
  "event":  "muteForced",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

Voir Propriétés JSON ci-dessous pour les descriptions.

Notez que vous devez définir l'option observeForceMute (pour true) lors de la création de la connexion SIP pour qu'il observe un événement de modération de type "force mute".

Propriétés JSON des événements de surveillance SIP

L'objet JSON comprend les propriétés suivantes :

sessionId -- L'identifiant de session associé à cet événement
applicationId -- L'identifiant du projet associé à cet événement
event -- callCreated | callUpdated | callDestroyed | muteForced
reason_code -- Pour un callDestroyed événement, reason_code est réglé sur l'une des valeurs suivantes :
- A code de réponse standard SIP pour capturer les erreurs dans le handshake SIP
- 700 -- "Effacement normal" -- Cette cause indique que l'appel est effacé parce qu'un des utilisateurs impliqués dans l'appel a demandé que l'appel soit effacé.
- 703 -- "Effacement inattendu" -- Cette cause indique que l'appel est effacé de façon inattendue.
- 704 -- "Media Timeout" -- Ce code indique que notre pont SIP n'a pas pu recevoir de trafic RTP de l'autre terminal SIP.
- 705 -- "Max Duration" -- L'appel a atteint la durée maximale.
- 706 -- "Max Inactive" -- L'appel a atteint la durée maximale d'inactivité.
reason_message -- Pour un callDestroyed événement, reason_message est une chaîne de caractères décrivant la raison pour laquelle l'appel a été détruit.
state -- Pour un callUpdated événement, state est réglé sur l'une des valeurs suivantes :
- DIALING -- Un appel SIP a été lancé
- RINGING -- L'appel SIP est en train de sonner
- ON_HOLD -- L'appel SIP est en attente
- ACTIVE -- Un appel SIP a été pris et est en cours.
- HANGUP -- Un appel SIP terminé
timestamp -- L'horodatage de l'événement, en millisecondes depuis l'époque Unix.
call -- Un objet définissant la connexion, contenant les propriétés suivantes :
- id -- L'identifiant de la conférence
- connectionId -- L'identifiant de connexion du client SIP
- createdAt -- La valeur de l'horodatage, en millisecondes depuis l'époque Unix, pour le moment où l'appel a été créé.

Considérations relatives à la sécurité

Vonage recommande certaines pratiques exemplaires lors de l'utilisation de l'interface SIP avec vos serveurs SIP. Elles tentent d'atténuer les attaques possibles en fournissant des mécanismes pour authentifier et autoriser que les appels SIP reçus dans votre serveur sont légitimes et pour crypter tous les signaux et les médias :

Utilisez TLS et activez les appels sécurisés (SRTP) pour la signalisation afin d'éviter toute possibilité d'interception des communications.
Activez l'authentification SIP sur votre serveur. Sinon, toute personne connaissant votre URI SIP pourrait envoyer des appels à votre serveur.

Contactez nous si vous avez des questions supplémentaires.

Détails techniques

Prise en charge de la norme RFC3550 (RTP/RTCP) : Le trafic média peut être crypté (SRTP) ou non crypté (RTP simple). En cas de cryptage, les protocoles DTLS et SDES sont pris en charge.

Prise en charge des codecs : La passerelle SIP de Vonage prend en charge les codecs audio OPUS, G.711 et G.722, ainsi que les codecs vidéo H.264 et VP8. La vidéo SIP est limitée à 480p à 800 kbps.

Signalisation : La passerelle SIP de Vonage supporte la RFC 3261 (SIP) sur UDP, TCP et TLS. Contactez Vonage si vous avez besoin d'informations ou de soutien pour une extension spécifique.

La passerelle SIP de Vonage rejettera tout message SIP provenant d'une plateforme SIP tierce, à moins qu'il ne fasse partie d'un dialogue SIP initié par la passerelle SIP de Vonage. Les appels initiés par la passerelle SIP de Vonage peuvent être mis en attente à l'aide d'un bouton re-INVITE avec le sendonly/inactive dans le SDP ou un re-INVITE avec le port 0 dans le SDP.

Autres considérations : Les médias précoces sont désactivés.

FAQ

Qu'est-ce que le SIP ? Pourquoi le SIP est-il important ?

Le protocole d'initiation de session (SIP) est un protocole de communication permettant de signaler et de contrôler les sessions de communication multimédia. Les Applications les plus courantes du SIP sont la téléphonie sur Internet pour les appels vocaux et vidéo, ainsi que la messagerie instantanée, sur les réseaux IP (Internet Protocol).

Dans notre cas, il est utilisé pour établir un appel entre des sessions et un serveur SIP tiers. Une fois l'appel établi, l'audio (et la vidéo, le cas échéant) est envoyé à l'aide du protocole RTP.

Quelle est la différence entre SIP et PSTN ? Est-ce que Vonage fournit une passerelle RTCP ?

Le RTC est le réseau téléphonique traditionnel. Le RTC n'est pas un réseau IP et n'utilise pas le protocole SIP, mais de nombreux fournisseurs, comme Nexmo, disposent de passerelles pour convertir les protocoles SIP en protocoles RTC. De cette manière, un appel SIP sur IP est converti en appel téléphonique.

Concrètement, même si l'API Video de Vonage ne prend pas en charge les appels RTPC, nous la rendons possible en prenant en charge les appels SIP. À partir de là, il s'agit de trouver un fournisseur pour convertir les appels SIP en appels RTC.

Puis-je appeler des téléphones ordinaires avec la fonction d'interconnexion SIP ?

L'interconnexion SIP de Vonage permet aux partenaires d'initier des appels vers n'importe quel point d'extrémité SIP. Pour passer/recevoir des appels vers/depuis un téléphone ordinaire, les clients ont besoin d'une passerelle de leur côté pour convertir l'appel SIP aux protocoles utilisés dans les réseaux de téléphonie mobile/fixe.

Existe-t-il un moyen de gérer les appels sortants ou entrants à partir d'un numéro de téléphone ordinaire (RTPC) ?

Avec SIP Interconnect, les clients peuvent se déconnecter d'une session vers n'importe quelle destination SIP. En outre, les clients peuvent configurer une passerelle SIP (la leur ou celle d'un tiers) pour se connecter à un numéro de téléphone ordinaire.

Bien que l'API d'interconnexion SIP ne prenne pas en charge les appels SIP entrants, les clients peuvent mettre en œuvre la composition à partir d'un téléphone ordinaire (RTPC) en utilisant une passerelle SIP (la leur ou celle d'un tiers) pour établir un pont entre l'appel entrant reçu d'un téléphone ordinaire et l'appel SIP sortant provenant de Vonage.

SIP Interconnect permet-il d'envoyer de la vidéo ?

Oui. video à true lors de l'initiation de l'appel SIP à l'aide de la fonction Méthode de l'API REST. La vidéo SIP est limitée à 480p à 800 kbps.

Y a-t-il une différence notable dans la qualité audio perçue sur le point d'extrémité WebRTC par rapport au point d'extrémité SIP ?

L'objectif est d'obtenir la même qualité, mais avec une latence supplémentaire au niveau du point d'extrémité SIP.

Comment la fonction d'archivage fonctionne-t-elle avec SIP Interconnect ?

La capacité d'archivage fonctionne exactement comme aujourd'hui pour une session WebRTC. Jusqu'à 16 flux vidéo et les 50 premiers flux audio, y compris les flux audio et vidéo SIP, feront partie de l'archive.

Comment l'utilisateur navigue-t-il dans le SVI ? Y aura-t-il un clavier de numérotation dans l'application web/mobile ?

Vous pouvez utiliser l'API REST pour envoyer des signaux DTMF à des clients SIP afin de prendre en charge des systèmes de réponse vocale interactive (IVR). Voir Envoi de signaux DTMF.

Avec quels serveurs SIP Interconnect est-il compatible ?

Nous avons testé l'interopérabilité avec certains des équipements de télécommunication les plus populaires (ACME packet, Broadsoft), certaines plateformes SIP populaires (Nexmo, et autres), et le serveur SIP open-source le plus populaire (freeswitch). Il est impossible de garantir l'interopérabilité avec chaque serveur SIP, mais nous essayons de limiter l'utilisation des extensions/fonctionnalités SIP afin de réduire les risques d'échec. Jusqu'à présent, nous n'avons jamais eu à modifier notre solution pour interopérer avec un nouveau serveur SIP.

Comment déconnecter un appel vers un client SIP connecté à une session ?

Utilisation de l'API client existante - Un client Web (JavaScript) connecté à une session avec des privilèges de modérateur peut forcer d'autres clients, y compris des clients SIP, à se déconnecter d'une session.

Utilisation de l'API REST pour la modération côté serveur - Si les clients WebRTC se trouvent sur des appareils mobiles ou si le client ne souhaite pas accorder des privilèges de modérateur aux clients, les serveurs d'applications peuvent émettre un HTTP DELETE à un client connecté pour forcer la déconnexion côté serveur.

Navigation

Introduction au SIP

Cas d'utilisation cibles

Lancer un appel SIP

Terminer un appel SIP

Envoi de signaux DTMF

Suivi de la progression de l'appel

Enregistrement des rappels

Surveillance de l'activité des appels SIP

Appel créé

Appel mis à jour

Appel détruit

Sourdine forcée

Propriétés JSON des événements de surveillance SIP

Considérations relatives à la sécurité

Détails techniques

FAQ

Qu'est-ce que le SIP ? Pourquoi le SIP est-il important ?

Quelle est la différence entre SIP et PSTN ? Est-ce que Vonage fournit une passerelle RTCP ?

Puis-je appeler des téléphones ordinaires avec la fonction d'interconnexion SIP ?

Existe-t-il un moyen de gérer les appels sortants ou entrants à partir d'un numéro de téléphone ordinaire (RTPC) ?

SIP Interconnect permet-il d'envoyer de la vidéo ?

Y a-t-il une différence notable dans la qualité audio perçue sur le point d'extrémité WebRTC par rapport au point d'extrémité SIP ?

Comment la fonction d'archivage fonctionne-t-elle avec SIP Interconnect ?

Comment l'utilisateur navigue-t-il dans le SVI ? Y aura-t-il un clavier de numérotation dans l'application web/mobile ?

Avec quels serveurs SIP Interconnect est-il compatible ?

Comment déconnecter un appel vers un client SIP connecté à une session ?