API de rappel Omichannel
L’API Omnichannel Callback fournit des méthodes pour créer ou mettre à jour une demande de rappel et pour récupérer les métadonnées connexes auprès d’un fournisseur CCaaS (Contact Center as a Service).
- Créez une nouvelle demande de rappel immédiat ou planifiez une nouvelle demande.
- Créez une interaction initiale et de nouvelles tentatives d’interaction ultérieures.
- Mettez à jour un rappel existant.
Cette API appartient à l’espace de noms sn_omni_callback et nécessite le rôle Administrateur avec API de rappel [sn_omni_callback.callback_api].
Pour plus d’informations sur l’application Rappel omnicanal en tant qu’option ServiceNow de plateforme IA, reportez-vous à la section Omnichannel Callback.
Rappel omnicanal : POST /api/sn_omni_callback/callback/attempt
Déclenche une interaction pour un rappel existant, y compris de nouvelles tentatives.
Format d'URL
URL par défaut : /api/sn_omni_callback/callback/attempt
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| Nom | Description |
|---|---|
| Aucun |
| Nom | Description |
|---|---|
| ID rappel | Requis. Sys_id ou external_id du rappel. Table : Rappel [sys_cs_callback] Type de données : chaîne |
| Détails de l’interaction | Facultatif. Détails sur l’interaction. Destiné aux types de rappels immédiats afin que les détails d’interaction soient acheminés directement à l’agent sans attendre. Tous les détails de l’interaction sont transmis dans la charge utile du Ressource d’interaction vocale : POST /cs/voice-interactions fichier . Type de données : objet |
| interactionDetails.numéronuméroTéléphoneAppelant | Numéro de téléphone de rappel de l’appelant. Il s’agit du numéro que l’agent utilise pour joindre l’appelant en cas d’interruption de l’appel. Type de données : chaîne Format : conforme à la norme E.164 Par défaut : aucun |
| interactionDetails.clientSessionId | Identificateur unique d’un enregistrement dans un système externe utilisé pour suivre cet appel téléphonique entre les systèmes, permettant l’intégration entre ServiceNow et des plateformes tierces (par exemple, les fournisseurs CCaaS). Type de données : chaîne Format : généralement un UUID ou un jeton de session unique généré par le système externe Par défaut : aucun |
| interactionDetails.userId | Sys_id de l’utilisateur à rappeler. Table : Utilisateur [user] Type de données : chaîne |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 400 | Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de la réponse (JSON ou XML)
| Nom | Description |
|---|---|
| erreurs | Message contenant des détails sur les échecs de la création du rappel, comme les ID de demande requis manquants. Type de données : tableau de chaînes |
| messages | Message contenant des détails sur la réussite de la création du rappel. Type de données : tableau de chaînes |
| résultat | Résultat de la demande. Type de données : objet |
| résultat.réponse | Objet contenant les ID de rappel et d’interaction de la demande de rappel. Type de données : objet |
| result.response.interaction_id | Sys_id de l’interaction nouvellement créée. Table : Interaction [interaction] Type de données : chaîne |
| résultat.état | État de réussite ou d’échec de la demande. Valeurs valides :
Type de données : chaîne |
Demande cURL
L’exemple suivant illustre une demande de tentative POST avec des détails sur l’interaction initiale et les interactions de nouvelles tentatives suivantes.
curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/attempt' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password' \
-d ' {
"callbackId": "<ID#>",
"interactionDetails": {
"clientSessionId": "<ID#>",
"userId": "<ID#>",
"callerPhoneNumber": "+112345678901"
}
}Corps de réponse lorsqu’une callback_Id valide est fournie et qu’une nouvelle interaction a été créée avec succès pour le rappel.
{
"result": {
"status": "success",
"response": {
"interaction_id": "<Interaction ID#>"
}
}
}Corps de réponse lorsqu’une callback_Id non valide a été fournie dans la demande.
{
"result": {
"status": "failure",
"response": {
"interactionId": null
},
"errors": [
"Callback not found for callback ID: <ID#>"
]
}
}Corps de réponse lorsque l’interaction existe déjà pour le rappel donné (le message renvoie des détails sur l’interaction existante) :
{
"result": {
"status": "success",
"response": {
"interaction_id": "<Interaction ID#>"
},
"messages": [
"Active Interaction <Interaction ID#> already exists for callback <ID#>"
]
}
}Rappel Omichannel : POST /api/sn_omni_callback/callback/create
Lance une nouvelle demande de rappel immédiat ou planifié en fonction des détails fournis dans le corps de la demande. Pour les rappels immédiats, cette API crée à la fois le rappel et l’interaction. Pour les rappels planifiés, crée le rappel et un rendez-vous.
Format d'URL
URL par défaut : /api/sn_omni_callback/callback/create
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| Nom | Description |
|---|---|
| Aucun |
| Nom | Description |
|---|---|
| callbackContext | Objet contenant les détails de contexte de la demande de rappel. Table : Contexte de rappel [sys_cs_callback_context] Type de données : objet |
| callbackContext.ivr_path | Le chemin IVR (serveur vocal interactif) qu’un client suit avant d’être transféré à un agent humain. Contient généralement une liste des files d’attente ou des options de menu que le client a parcourues dans le système IVR. Cette chaîne est transmise par le Centre de contact en tant que service (CCaaS). Par exemple, Type de données : chaîne |
| callbackContext.queue | Numérotez les affectations dans la file d’attente. Type de données : chaîne |
| détails de rappel | Objet contenant les détails de la demande de rappel. Table : Rappel [sys_cs_callback] Type de données : objet |
| callbackDetails.appointment | Sys_id du rendez-vous. Applicable uniquement à un type de rappel planifié .Table : Prise de rendez-vous [sn_apptmnt_booking_appointment_booking] Type de données : chaîne |
| callbackDetails.channel_to_callback | Canal de messagerie cible par lequel acheminer le rappel. Table : Canal de messagerie [sys_cs_channel], Champ : sys_id Type de données : chaîne |
| callbackDetails.description | Description complète décrivant le motif du rappel, si nécessaire. Type de données : chaîne |
| callbackDetails.end_time | Valeur de date et d’heure d’arrêt de la tentative de rappel. Applicable uniquement à un type de rappel planifié .Format : valeur glide_date_time, par exemple Type de données : chaîne |
| callbackDetails.expire_time | Date et heure de fermeture de la demande de rappel. Format : valeur glide_date_time, par exemple Type de données : chaîne |
| callbackDetails.messaging_channel | Source du rappel. Identifie l’interface client à l’origine de la demande de rappel, par exemple un client Web, une application mobile ou une messagerie incorporée. Table : Canal de messagerie [sys_cs_channel], Champ : sys_id Type de données : chaîne |
| callbackDetails.reason_type | Motif de la demande de rappel. Aide à l’acheminement, à l’analyse et à la génération de rapports en balisant le rappel avec un motif standardisé. Valeurs valides :
Table : Rappel [sys_cs_callback], Champ : reason_type Type de données : chaîne |
| callbackDetails.scheduled_date_time | Valeur de date et d’heure de lancement du rappel. Applicable uniquement à un type de rappel planifié .Format : valeur glide_date_time, par exemple Type de données : chaîne |
| callbackDetails.short_description | Fournit une explication détaillée de la demande de rappel. Peut inclure des préoccupations client spécifiques, le contexte ou des notes de l’agent. Type de données : chaîne |
| callbackDetails.user_document | Sys_id de l’utilisateur qui a demandé le rappel. Utilisé avec pour callbackDetails.user_table identifier l’utilisateur demandant le rappel. Table : utilisateur [sys_user], champ : sys_id Type de données : chaîne |
| callbackDetails.user_table | Table dans laquelle réside l’enregistrement utilisateur. Utilisé avec pour callbackDetails.user_document identifier l’utilisateur demandant le rappel. La valeur est toujours sys_user.Type de données : chaîne |
| externalCallbackId | Identificateur externe du rappel qui a été créé dans un fournisseur tiers. Type de données : chaîne |
| inboundId | Sys_id de l’appel entrant associé au rappel. Fournit une traçabilité liant la demande de rappel à un enregistrement d’appel entrant spécifique qui peut provenir d’un fournisseur tiers ou d’une plateforme CCaaS. Table : Rappel [sys_cs_callback], Champ : provider_application_id Type de données : chaîne |
| Détails de l’interaction | Facultatif. Détails sur l’interaction. Destiné aux types de rappels immédiats afin que les détails d’interaction soient acheminés directement à l’agent sans attendre. Tous les détails de l’interaction sont transmis dans la charge utile du Ressource d’interaction vocale : POST /cs/voice-interactions fichier . Type de données : objet |
| interactionDetails.numéronuméroTéléphoneAppelant | Numéro de téléphone de rappel de l’appelant. Il s’agit du numéro que l’agent utilise pour joindre l’appelant en cas d’interruption de l’appel. Type de données : chaîne Format : conforme à la norme E.164 Par défaut : aucun |
| interactionDetails.clientSessionId | Identificateur unique d’un enregistrement dans un système externe utilisé pour suivre cet appel téléphonique entre les systèmes, permettant l’intégration entre ServiceNow et des plateformes tierces (par exemple, les fournisseurs CCaaS). Type de données : chaîne Format : généralement un UUID ou un jeton de session unique généré par le système externe Par défaut : aucun |
| interactionDetails.userId | Sys_id de l’utilisateur à rappeler. Table : Utilisateur [user] Type de données : chaîne |
| isExternal | Marqueur indiquant si le rappel est externe et a été demandé auprès d’un autre fournisseur tiers. Valeurs valides :
Valeur par défaut : false |
| type | Requis. Type de rappel. Valeurs valides :
Type de données : chaîne |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 400 | Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de la réponse (JSON ou XML)
| Nom | Description |
|---|---|
| résultat | Résultat de la demande. Type de données : objet |
| résultat.erreurs | Message contenant des détails sur les échecs de la création du rappel, comme les ID de demande requis manquants. Type de données : tableau de chaînes |
| résultats.messages | Message contenant des détails sur la réussite de la création du rappel. Type de données : tableau de chaînes |
| résultat.réponse | Objet contenant les ID de rappel et d’interaction de la demande de rappel. Type de données : objet |
| result.response.callback_created |
Marqueur indiquant si la nouvelle demande de rappel a été créée ou non. Valeurs possibles :
Type de données : booléennes |
| result.response.callback_id | Sys_id du nouveau rappel, le cas échéant. Table : Rappel [sys_cs_callback] Type de données : chaîne |
| result.response.interaction_id | Sys_id de l’interaction nouvellement créée. Table : Interaction [interaction] Type de données : chaîne |
| résultat.état | État de réussite ou d’échec de la demande. Valeurs valides :
Type de données : chaîne |
Demande cURL
L’exemple suivant crée une demande de rappel simple en fonction des détails fournis par l’agent dans le corps de la demande.
curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/create' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password' \
-d ' {
"type": "immediate",
"callbackDetails": {
"appointment": "68cc0a5a9314521060320dd548373cbd",
"description": "Customer reported issue with order #12345",
"short_description": "Order issue",
"reason_type": "product_issue",
"expire_time": "2025-09-01 17:00",
"messaging_channel": "web_channel_sys_id",
"channel_to_callback": "genesys_channel_sys_id",
"scheduled_start_time: "2025-09-01 1:00",
"end_time": "2025-09-01 17:00",
"user_document": "abel.tuter",
"user_table": "sys_user"
},
},
"callbackContext": {
"queue": "21 value changed via api",
"ivr_path": "21 some-ivr-path changed via api"
},
"inboundId": "ServiceNowVoice",
"isExternal": true,
"externalCallbackId": "new-external-id",
"interactionDetails": {
"clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z",
"userId": "32423424",
"callerPhoneNumber": "+14089178877"
}
}Le corps de la réponse renvoie une réponse de réussite avec des ID de rappel et d’interaction pour la demande de rappel nouvellement créée.
{
"status": "success",
"response": {
"callback_id": "a16ead53fff0621088c6ffffffffffce",
"interaction_id": "696e6d57fff0621088c6ffffffffff7d"
}
}Corps de réponse lorsque les détails de l’interaction n’ont pas été fournis :
{
"status": "success",
"response": {
"callback_created": true,
"callback_id": "7df2059ffffc221088c6ffffffffff0c"
}
}Corps de réponse lorsque l’ID de rappel existe déjà, mais que de nouveaux détails d’interaction ont été fournis :
{
"result": {
"status": "success",
"response": {
"interaction_id": "84054fff53786210011eddeeff7b12d6",
"callback_id": "8b43c3fb53786210011eddeeff7b12a6",
“callback_created”: false
},
"messages": [
"Successfully updated the callback 8b43c3fb53786210011eddeeff7b12a6",
"Successfully created the interaction 84054fff53786210011eddeeff7b12d6"
]
}
}Corps de réponse lorsque l’ID de rappel existe déjà, mais que les nouveaux détails d’interaction n’ont pas été fournis :
{
"result": {
"status": "success",
"response": {
"callback_id": "8b43c3fb53786210011eddeeff7b12a6"
},
"messages": [
"Successfully updated the callback 8b43c3fb53786210011eddeeff7b12a6"
]
}
}Corps de réponse lorsque des champs obligatoires sont manquants dans la demande :
{
"result": {
"status": "failure",
"response": {
"callbackId": null
},
"errors": [
"Parameter 'type' is required in request"
]
}
}Rappel omnicanal : PATCH /api/sn_omni_callback/callback/update
Met à jour un rappel existant en fonction des détails fournis dans la demande.
Indiquez uniquement les paramètres de demande dans le corps de la demande que vous souhaitez mettre à jour.
Format d'URL
URL par défaut : /api/sn_omni_callback/callback/update
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| Nom | Description |
|---|---|
| Aucun |
| Nom | Description |
|---|---|
| callbackContext | Objet contenant les détails de contexte de la demande de rappel. Table : Contexte de rappel [sys_cs_callback_context] Type de données : objet |
| callbackContext.ivr_path | Le chemin IVR (serveur vocal interactif) qu’un client suit avant d’être transféré à un agent humain. Contient généralement une liste des files d’attente ou des options de menu que le client a parcourues dans le système IVR. Cette chaîne est transmise par le Centre de contact en tant que service (CCaaS). Par exemple, Type de données : chaîne |
| callbackContext.queue | Numérotez les affectations dans la file d’attente. Type de données : chaîne |
| détails de rappel | Objet contenant les détails de la demande de rappel. Table : Rappel [sys_cs_callback] Type de données : objet |
| callbackDetails.appointment | Sys_id du rendez-vous. Applicable uniquement à un type de rappel planifié .Table : Prise de rendez-vous [sn_apptmnt_booking_appointment_booking] Type de données : chaîne |
| callbackDetails.channel_to_callback | Canal de messagerie cible par lequel acheminer le rappel. Table : Canal de messagerie [sys_cs_channel], Champ : sys_id Type de données : chaîne |
| callbackDetails.description | Description complète décrivant le motif du rappel, si nécessaire. Type de données : chaîne |
| callbackDetails.end_time | Valeur de date et d’heure d’arrêt de la tentative de rappel. Applicable uniquement à un type de rappel planifié .Format : valeur glide_date_time, par exemple Type de données : chaîne |
| callbackDetails.expire_time | Date et heure de fermeture de la demande de rappel. Format : valeur glide_date_time, par exemple Type de données : chaîne |
| callbackDetails.messaging_channel | Source du rappel. Identifie l’interface client à l’origine de la demande de rappel, par exemple un client Web, une application mobile ou une messagerie incorporée. Table : Canal de messagerie [sys_cs_channel], Champ : sys_id Type de données : chaîne |
| callbackDetails.reason_type | Motif de la demande de rappel. Aide à l’acheminement, à l’analyse et à la génération de rapports en balisant le rappel avec un motif standardisé. Valeurs valides :
Table : Rappel [sys_cs_callback], Champ : reason_type Type de données : chaîne |
| callbackDetails.scheduled_date_time | Valeur de date et d’heure de lancement du rappel. Applicable uniquement à un type de rappel planifié .Format : valeur glide_date_time, par exemple Type de données : chaîne |
| callbackDetails.short_description | Fournit une explication détaillée de la demande de rappel. Peut inclure des préoccupations client spécifiques, le contexte ou des notes de l’agent. Type de données : chaîne |
| callbackDetails.user_document | Sys_id de l’utilisateur qui a demandé le rappel. Utilisé avec pour callbackDetails.user_table identifier l’utilisateur demandant le rappel. Table : utilisateur [sys_user], champ : sys_id Type de données : chaîne |
| callbackDetails.user_table | Table dans laquelle réside l’enregistrement utilisateur. Utilisé avec pour callbackDetails.user_document identifier l’utilisateur demandant le rappel. La valeur est toujours sys_user.Type de données : chaîne |
| ID rappel | Requis. Sys_id ou external_id du rappel. Table : Rappel [sys_cs_callback] Type de données : chaîne |
| inboundId | Sys_id de l’appel entrant associé au rappel. Fournit une traçabilité liant la demande de rappel à un enregistrement d’appel entrant spécifique qui peut provenir d’un fournisseur tiers ou d’une plateforme CCaaS. Table : Rappel [sys_cs_callback], Champ : provider_application_id Type de données : chaîne |
| phoneNumber | Numéro de téléphone de l’appelant. Type de données : chaîne de nombres Format : conforme à la norme E.164 |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 400 | Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de la réponse (JSON ou XML)
| Nom | Description |
|---|---|
| erreurs | Message contenant des détails sur les échecs de la création du rappel, comme les ID de demande requis manquants. Type de données : tableau de chaînes |
| messages | Message contenant des détails sur la réussite de la création du rappel. Type de données : tableau de chaînes |
| résultat | Résultat de la demande. Type de données : objet |
| résultat.réponse | Objet contenant les ID de rappel et d’interaction de la demande de rappel. Type de données : objet |
| result.response.callback_created |
Marqueur indiquant si la nouvelle demande de rappel a été créée ou non. Valeurs possibles :
Type de données : booléennes |
| result.response.callback_id | Sys_id du nouveau rappel, le cas échéant. Table : Rappel [sys_cs_callback] Type de données : chaîne |
| result.response.interaction_id | Sys_id de l’interaction nouvellement créée. Table : Interaction [interaction] Type de données : chaîne |
| résultat.état | État de réussite ou d’échec de la demande. Valeurs valides :
Type de données : chaîne |
Demande cURL
L’exemple suivant met à jour certains détails de rappel dans la demande de rappel associée.
curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/update' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password' \
-d ' {
"callbackDetails": {
"appointment": "68cc0a5a9314521060320dd548373cbd",
"description": "Customer reported issue with order #12345",
"short_description": "Order issue",
"reason_type": "product_issue",
"expire_time": "2025-09-01 17:00",
"messaging_channel": "web_channel_sys_id",
"channel_to_callback": "genesys_channel_sys_id",
"scheduled_start_time: "2025-09-01 1:00",
"end_time": "2025-09-01 17:00",
"user_document": "abel.tuter",
"user_table": "sys_user"
},
"callbackContext": {
"queue": "5 value changed via api",
"ivr_path": "5 some-ivr-path changed via api"
},
"inboundId": "AmazonConnect",
"phoneNumber": "+14089178877",
"callbackId": "a16ead53fff0621088c6ffffffffffce"
}Réponse d’une mise à jour réussie de l’ID de rappel valide existant.
{
"result": {
"status": "success",
"response": {
"callback_id": "952f763b53786210011eddeeff7b1297"
},
"messages": [
"Successfully updated the callback 952f763b53786210011eddeeff7b1297"
]
}
}
"result": {
"status": "failure",
"response": {
"callbackId": null
},
"errors": [
"Callback not found for callback ID: 952f763b53786210011eddeef7b1297"
]
}
}
"result": {
"status": "failure",
"response": {
"callbackId": null
},
"errors": [
"Parameter 'callbackId' is required in request"
]
}
}