Documentation de référence de l'API Interactive Canvas

L'API Interactive Canvas est une bibliothèque JavaScript qui vous permet d'interagir avec votre action conversationnelle à l'aide de l'objet interactiveCanvas de votre application Web.

Remarque :L'objet interactiveCanvas est associé à l'objet window. Si vous utilisez un framework frontend pour développer votre application Web, vous devez vous assurer que vous avez accès à window pour configurer l'API.

Pour en savoir plus sur Interactive Canvas, consultez la documentation d'Interactive Canvas.

Méthodes

Avertissement: Certaines API d'Interactive Canvas sont actuellement en version Preview développeur. Vous pouvez tester les API dans le simulateur, mais ne déployez pas d'action qui utilise ces fonctionnalités en versions alpha, bêta ou de production. Les actions déployées à l'aide de ces fonctionnalités ne fonctionneront pas sur les appareils des utilisateurs finaux.

prêt

ready(callbacks) returns undefined

Appelée par l'application Web Interactive Canvas une fois qu'elle est chargée pour enregistrer les rappels.

Paramètres
callbacks	InteractiveCanvasCallbacks Objet contenant des rappels de méthode.

Remarque :Vous devez appeler l'API ready dans l'application Web dès que la page est chargée. Sinon, l'action se ferme.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Envoie une requête textuelle à l'action de conversation.

Paramètres
textQuery	string Requête à envoyer à l'action de conversation.
state	string Choisissez l'une des options suivantes : READY: Les requêtes peuvent être acceptées par la plate-forme. BLOCKED: Une requête est en cours de transfert et la nouvelle requête sera ignorée. UNKNOWN: Impossible de déterminer l'état actuel de la requête.

Attention :textQuery ne doit pas comporter plus de 640 caractères.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

Détermine la hauteur de l'en-tête en haut d'un écran.

Paramètres
height	number Hauteur en pixels.

outputTts

outputTts(text, openMic) returns undefined;

Lit du texte SSML.

Paramètres
text	string Chaîne à lire compatible avec le SSML.
openMic	boolean Permet de spécifier si le micro doit être activé ou non après la lecture de la synthèse vocale.

createIntentHandler

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

createIntentHandler(intentId, callback) returns IntentHandler

Crée un gestionnaire d'intent pour un intent personnalisé NLU.

Paramètres
intentId	string Nom de l'intent tel que défini dans Actions Builder.
callback	function(MatchedIntent) Fonction à exécuter lorsque l'intent est mis en correspondance.
IntentHandler	object Objet de gestionnaire d'intents pouvant être enregistré à l'aide de expect().

IntentHandler

Objet représentant un gestionnaire d'intents. Enregistrement possible à l'aide de expect() ou de prompt().

MatchedIntent

Objet contenant les données d'un intent correspondant.

Méthodes
getIntentArg(parameterName)	function(string) Méthode permettant d'obtenir le paramètre d'intent d'un intent correspondant.

createNumberSlot

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

createNumberSlot(callback, hints?) returns Slot<number>

Crée un emplacement de type number.

Paramètres
callback	function(FilledSlot) Fonction à exécuter lorsque l'espace est rempli.
hints	Hints Mots courts que l'utilisateur pourrait dire lorsqu'il remplit un emplacement. hints aident le système NLU à décider quel emplacement remplir.
Slot	object Objet Slot qui peut être enregistré à l'aide de prompt().

createTextSlot

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

createTextSlot(callback, hints?) returns Slot<string>

Crée un emplacement de type chaîne.

Paramètres
callback	function(FilledSlot) Fonction à exécuter lorsque l'espace est rempli.
hints	Hints Mots courts que l'utilisateur pourrait dire lorsqu'il remplit un emplacement. hints aident le système NLU à décider quel emplacement remplir.
Slot	object Objet Slot qui peut être enregistré à l'aide de prompt().

createConfirmationSlot

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

createConfirmationSlot(callback, hints?) returns Slot<boolean>

Crée un emplacement de type booléen.

Paramètres
callback	function(FilledSlot) Fonction à exécuter lorsque l'espace est rempli.
hints	Hints Mots courts que l'utilisateur pourrait dire lorsqu'il remplit un emplacement. hints aident le système NLU à décider quel emplacement remplir.
Slot	object Objet Slot qui peut être enregistré à l'aide de prompt().

createOptionsSlot

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

createOptionsSlot(options, callback, hints?) returns Slot<string>

Crée un emplacement à partir d'une liste prédéfinie d'options.

Paramètres
options	array<Option> Fonction à exécuter lorsque l'espace est rempli.
callback	function(FilledSlot) Fonction à exécuter lorsque l'espace est rempli.
hints	Hints Mots courts que l'utilisateur pourrait dire lorsqu'il remplit un emplacement. hints aident le système NLU à décider quel emplacement remplir.
Slot	object Objet Slot qui peut être enregistré à l'aide de prompt().

Encoche

Objet représentant un emplacement à remplir. Enregistrement possible à l'aide de expect() ou de prompt().

FilledSlot<T>

Objet représentant un espace publicitaire rempli.

Paramètres
T	boolean|number|string Type d'emplacement.

Option

Objet représentant une entrée de type d'emplacement.

Champs
key	string Identifiant unique de l'entrée du type d'emplacement.
synonyms	array<string> Liste de mots utilisée pour sélectionner l'option d'emplacement.

Astuces

Objet représentant des suggestions pour un emplacement.

Champs
associatedWords	array<string> Liste de mots utilisée pour aider le système NLU à décider quel emplacement remplir.

expect

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

expect(expectation) returns HandlerRegistration

Enregistre l'attente sur le client. Peut être appelé sur les gestionnaires d'intents et les emplacements.

Paramètres
expectation	IntentHandler|Slot Gestionnaire d'intent ou emplacement à enregistrer.
HandlerRegistration	object Gestionnaire d'intents ou emplacement enregistrés.

HandlerRegistration

Objet représentant un gestionnaire d'intents enregistré.

Méthodes
deleteHandler()	function Annule l'enregistrement du gestionnaire d'intent attendu.

clearExpectations

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

clearExpectations() returns undefined;

Supprime toutes les attentes en supprimant tous les gestionnaires d'intents et emplacements précédemment enregistrés.

invite

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

prompt(tts, expectation) returns Promise<Answer<T>>

Invite l'utilisateur avec la chaîne de synthèse vocale fournie et enregistre l'attente sur le client. Peut être appelé sur les gestionnaires d'intents et les emplacements.

Paramètres
tts	string Chaîne de synthèse vocale utilisée pour demander à l'utilisateur l'attente fournie.
expectation	IntentHandler|Slot Gestionnaire d'intent ou emplacement à enregistrer.
Answer<T>	object Réponse fournie par l'utilisateur à l'invite.

Réponse<T>

Objet représentant une réponse fournie par l'utilisateur à une invite.

Champs
value	boolean|number|string Valeur de la réponse fournie par l'utilisateur.
status	string État de la réponse. Choisissez l'une des options suivantes : ANSWERED: L'utilisateur a répondu à l'invite. NO_MATCH: L'utilisateur a été invité à fournir une réponse et a donné une réponse qui ne correspondait pas à la réponse attendue ni à aucun autre intent prévu. YIELD: L'utilisateur a répondu à l'invite avec un autre intent.

triggerScene

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

Déclenche une scène.

Paramètres
sceneName	string Nom de la scène à déclencher.
TriggerSceneStatus	string État de l'appel à triggerScene(). Choisissez l'une des options suivantes : SUCCESS: La requête a bien été traitée par le serveur. BLOCKED: La requête a été bloquée par une requête existante en cours de diffusion. UNKNOWN: L'état de la requête est inconnu.

setUserParam

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

setUserParam(key, value) returns Promise<undefined>;

Définit la paire clé-valeur transmise et conservée entre les conversations.

Paramètres
key	string Clé du paramètre.
value	object|array|boolean|number|string Valeur du paramètre.

getUserParam

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

getUserParam(key) returns Promise<object|array|boolean|number|string>;

Récupère la valeur de paramètre de la clé donnée si elle existe et l'état de l'appel.

Paramètres
key	string Clé du paramètre.

resetUserParam

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

resetUserParam() returns Promise<void>;

Efface tous les paramètres utilisateur.

setHomeParam

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

setHomeParam(key, value) returns Promise<undefined>;

Définit la paire clé-valeur transmise et conservée entre les conversations.

Paramètres
key	string Clé du paramètre.
value	object|array|boolean|number|string Valeur du paramètre.

getHomeParam

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

getHomeParam(key) returns Promise<object|array|boolean|number|string>;

Récupère la valeur de paramètre de la clé donnée si elle existe et l'état de l'appel.

Paramètres
key	string Clé du paramètre.

resetHomeParam

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

resetHomeParam() returns Promise<void>;

Efface tous les paramètres utilisateur.

setCanvasState

setCanvasState(state) returns undefined

Notifie l'Assistant que l'état de l'application Web Canvas a été modifié. La méthode setCanvasState ne renvoie aucune valeur. La charge utile de l'état est accessible via la propriété conv.context.canvas.state.

Attention :La longueur de la représentation de l'objet state sous forme de chaîne doit être inférieure ou égale à 50 000 caractères. Si la chaîne dépasse 50 000 caractères, une erreur est générée.

Paramètres
state	Object État mis à jour de l'application Canvas en tant qu'objet JSON.

InteractiveCanvasCallbacks

Ces rappels vous permettent de répondre aux informations ou aux requêtes de votre action de conversation, tandis que les méthodes vous permettent d'envoyer des informations ou des requêtes à votre action de conversation.

onUpdate

onUpdate(data) returns Promise|undefined

Appelée lorsqu'une réponse Canvas est envoyée à partir de l'action conversationnelle. La synthèse vocale démarre une fois la promesse renvoyée résolue ou expire au bout de 10 secondes.

Paramètres
data	Object Données envoyées par le webhook.

onTtsMark

onTtsMark(markName) returns undefined

Rappel invoqué lors de la lecture par synthèse vocale.

Signes spéciaux qui sont toujours déclenchés:

• START indique le début de la synthèse vocale.
• END indique la fin de la synthèse vocale.
• ERROR indique une erreur de lecture de la synthèse vocale.

Vous pouvez également définir des marques personnalisées à l'aide de SSML et de la balise <mark>, comme <mark name="custom"/>.

Remarque:Les marques SSML ne sont pas appelées dans les cas suivants :

• Avant le début de la synthèse vocale, l'utilisateur appuie sur le micro, ou le client Interactive Canvas appelle sendTextQuery. La synthèse vocale est annulée et toutes les marques SSML qui y figurent sont ignorées.
• Pendant la synthèse vocale, l'utilisateur appuie sur le micro ou le client Interactive Canvas appelle sendTextQuery. La synthèse vocale est interrompue et toutes les marques SSML restantes sont ignorées.

Paramètres
markName	string Marquez le nom invoqué pendant la lecture par synthèse vocale.

onInputStatusChanged

Attention: Cette API est actuellement en version Preview développeur. Vous pouvez tester cette API dans le simulateur, mais ne déployez pas d'action qui utilise cette fonctionnalité en version alpha, bêta ou de production. Les actions déployées à l'aide de cette fonctionnalité ne fonctionneront pas sur les appareils des utilisateurs finaux.

onInputStatusChanged(inputStatus) returns undefined

Notifie l'application Canvas que l'état de saisie par l'Assistant a changé.

Paramètres
inputStatus	Enum État du traitement de la saisie vocale et/ou de texte sur l'appareil. Il peut s'agir des types de fichiers suivants: LISTENING : le micro est activé. IDLE : le micro est désactivé. PROCESSING : l'Assistant exécute actuellement une requête (le micro est fermé).