Aller au contenu principal
Version: 3.2.1

Structures de données et types

Ce document fournit des exemples complets des structures de données et types acceptés par le SDK JavaScript Optave version 3.

Aperçu​

Le SDK Optave v3 accepte des payloads structurés contenant des informations sur les sessions et les requêtes. Le SDK utilise une validation JSON Schema (via AJV) pour garantir l'intégrité des données.

Structure principale du payload​

Le payload v3 se compose de trois sections principales :

  • headers : En-têtes d'enveloppe pour suivi, versionnage et corrélation
  • session : Informations de session, canal et interface
  • request : Détails de requête (context, connections, attributes, scope, settings, fonctions avancées)

Enveloppe de message (Version 3+)​

Les messages version 3+ sont encapsulés dans une enveloppe avec des en-têtes :

{
  action: "message",
  headers: {
    correlationId: "a1b2c3d4-e5f6-7890-1234-56789ab2345", // UUID auto-généré si absent
    tenantId: "tenant-123", // Fourni par Optave lors de l'initialisation du SDK
    traceId: "trace-456", // UUID auto-généré pour la traçabilité
    idempotencyKey: "idem-789",
    identifier: "message",
    action: "customerinteraction", // Action spécifique exécutée
    schemaRef: "optave.message.v3",
    sdkVersion: "3.2.1", // Utilisez "none" si vous n'utilisez pas le SDK
    networkLatencyMs: 120,
    timestamp: "2024-01-15T10:30:00.000Z",
    issuedAt: "2024-01-15T10:30:00.000Z"
  },
  payload: {
    // Objets session et request (voir ci-dessous)
  }
}
Vous n'utilisez pas le SDK ?

Si vous intégrez directement sans le SDK JavaScript Optave, définissez sdkVersion à "none" dans les en-têtes de votre message :

sdkVersion: "none"

Référence des types​

Objet session​

Contient les informations de suivi de session, de canal et d'interface.

session: {
  sessionId: "session-12345",  // string - Identifiant personnalisé de session
  channel: {                    // object - Informations de canal
    browser: "Safari 17.0",          // string
    deviceInfo: "iOS/18.2, iPhone15,3",   // string
    deviceType: "mobile",            // string
    language: "fr-FR",               // string
    location: "45.42,-75.69",        // string - Coordonnées géographiques
    medium: "chat",                  // string - "chat", "voice", "email"
    metadata: [],                     // array - Métadonnées personnalisées
    section: "product_page"          // string
  },
  interface: {                 // object - Détails de l'interface
    appVersion: "1.2.3",            // string
    category: "crm",                // string
    language: "fr-FR",              // string
    name: "salesforce",             // string
    type: "custom_components"       // string
  }
}

Objet request​

Définit les paramètres de la requête : context, connections, attributes, scope et settings.

request: {
  requestId: "a1b2c3d4-e5f6-7890-1234-56789ab2345", // string - Identifiant unique
  attributes: {                            // object - Attributs optionnels
    content: "Comment puis-je vous aider ?", // string
    instruction: "Rester utile et courtois", // string
    variant: "A"                            // string
  },
  connections: {                           // object - Relations de connexion
    journeyId: "journey-456",             // string
    parentId: "parent-789",               // string - ID parent (adjust/elevate)
    threadId: "thread-123"                // string - Identifiant de thread (OBLIGATOIRE)
  },
  context: {                               // object - Contexte (généré par Optave)
    caseId: "case-456",                   // string
    departmentId: "dept-789",             // string
    operatorId: "op-012",                 // string
    organizationId: "org-345",            // string
    userId: "user-678"                    // string
  },
  reference: {                             // object - Informations de référence (optionnel)
    ids: [                                 // array
      { name: "ticket_id", value: "T12345" },
      { name: "order_id", value: "O67890" }
    ],
    labels: ["priorité", "escalade"],    // array
    tags: ["support", "urgent"]          // array
  },
  resources: {                             // object - Ressources
    codes: [                               // array
      {
        id: "10382320302",                // string
        label: "Numéro de commande",      // string
        type: "order_number",             // string
        value: "CMD-56789"                // string
      }
    ],
    links: [                               // array
      {
        expires_at: "2025-08-06T00:00:00Z", // string
        html: false,                       // boolean
        id: "20382320302",                // string
        label: "Payer ici",               // string
        type: "payment_link",             // string
        url: "https://checkout.stripe.com/pay/cs_test..." // string
      }
    ],
    offers: []                             // array
  },
  scope: {                                 // object - Données contextuelles
    accounts: [],
    appointments: [],
    assets: [],
    bookings: [],
    cases: [],
    conversations: [                       // array - Historique de conversation (souvent requis)
      {
        conversationId: "conv-123",
        participants: [
          {
            participantId: "participant-456",
            displayName: "Jean Dupont",
            role: "user"
          },
          {
            participantId: "participant-789",
            displayName: "Agent Martin",
            role: "operator"
          }
        ],
        messages: [
          {
            content: "J'ai besoin d'aide pour ma commande",
            participantId: "participant-456",
            timestamp: "2024-01-15T10:30:00.000Z"
          },
          {
            content: "Je vais vous aider avec cela",
            participantId: "participant-789",
            timestamp: "2024-01-15T10:30:15.000Z"
          }
        ],
        metadata: {}
      }
    ],
    documents: [],
    events: [],
    interactions: [                        // array - Interactions système
      {
        content: "Commande trouvée : #12345",
        id: "interaction-123",
        name: "order_lookup",
        role: "system",
        timestamp: "2024-01-15T10:30:00.000Z"
      }
    ],
    items: [],
    locations: [],
    offers: [],
    operators: [],
    orders: [],
    organizations: [],
    persons: [],
    policies: [],
    products: [
      { id: "prod-123" }
    ],
    properties: [],
    services: [],
    subscriptions: [],
    tickets: [],
    transactions: [],
    users: []
  },
  settings: {                              // object - Paramètres de requête
    disableBrowsing: false,
    disableSearch: false,
    disableSources: false,
    disableStream: true,
    disableTools: false,
    maxResponseLength: 0,
    overrideInterfaceLanguage: "",
    overrideOutputLanguage: ""
  },
  a2a: [                                    // Mode avancé - agent to agent
    {
      id: "bot_55",
      name: "Bot 55",
      type: "chatbot"
    }
  ],
  cursor: {                                 // Curseur temporel
    since: "2024-01-15T10:30:00.000Z",
    until: "2024-01-15T11:00:00.000Z"
  }
}

Contraintes des types​

Champs string​

  • Chaînes UTF-8 valides
  • Chaînes vides autorisées pour les champs optionnels
  • Champs requis validés par le schéma

Tableaux​

  • Peuvent contenir objets ou types primitifs
  • Tableaux vides [] autorisés
  • Lorsqu'un tableau est fourni il remplace la valeur par défaut

Booléens​

  • Acceptent true ou false
  • Valeurs par défaut utilisées si non spécifiées

Nombres​

  • integer : nombres entiers
  • number : nombres décimaux

Date-Heure​

  • Format ISO 8601 : "2024-01-15T10:30:00Z"
  • Peuvent être null si optionnels

Champs requis​

Champs requis universels​

Niveau requête​

  • request.connections.threadId - Identifiant de thread
  • request.scope.conversations - Tableau de conversations (non vide pour la plupart des actions)

Champs requis par type d'action​

interaction/customerinteraction/reception​

  • request.connections.threadId

adjust​

  • request.connections.threadId
  • request.connections.parentId
  • request.attributes.content
  • request.attributes.instruction
  • request.scope.conversations

elevate​

  • request.connections.threadId
  • request.connections.parentId
  • request.attributes.content
  • request.scope.conversations

translate, summarize, insights​

  • request.connections.threadId
  • request.scope.conversations

recommend​

  • request.connections.threadId
  • request.resources.offers - Tableau non vide d'offres
  • request.scope.conversations

Catégories d'erreurs​

Le SDK version 3.2.1 inclut une gestion d'erreurs avec les catégories suivantes :

  • AUTHENTICATION - Problèmes d'identifiants ou d'authentification
  • ORCHESTRATOR - Erreurs de traitement côté serveur
  • VALIDATION - Erreurs de validation ou champs manquants
  • WEBSOCKET - Erreurs de connexion / communication