Accueil

Contrats d'Interface - Orchestrateur Temporal Notifications EAgence

Ce document décrit de manière claire et actionnable les contrats d'interface à utiliser pour l'envoi de notifications via l'orchestrateur Temporal et les microservices (Push, Email, SMS). Il couvre les envois ciblés et broadcast, ainsi que la sémantique de criticité (planification).

Topic d'entrée application:

eagence.orchestration-requests

1) Base Orchestrateur - Requête Application EAgence

Interface 

{
  messageId?: string,
  correlationId?: string,
  batchId?: string,
  timestamp?: string, // ISO
  criticality: number, // 1 = immédiat ; >1 = fenêtre 6h-22h (Abidjan)
  mode_test?: boolean,
  test_date?: string, // ISO, requis si mode_test
  channels?: {
    push?: { enabled?: boolean, excludedUserIds?: string[] },
    email?: { enabled?: boolean, recipients?: string[] }, // ["broadcast"] supporté
    sms?:   { enabled?: boolean, recipients?: string[] }  // ["broadcast"] supporté
  },
  content?: {
    push?: {
      title?: string,
      body?: string,
      data?: {
        type?: "technical" | "functional_client" | "functional_backoffice",
        eventType?: "account_connection" | "account_disconnection" | "level2_attachment" | "level2_detachment" | "enrollment" | "new_bill" | "bill_payment" | "prepaid_purchase" | "request_status_change" | "payment_confirmation" | "overdue_reminder" | "cutoff_alert" | "supply_stop_alert" | "quote_available" | "custom_message" | "new_request" | "request_status_update",
        eventData?: object,
        clientId?: string,
        deviceId?: string,
        locale?: string,
        details?: object,
        customFields?: object
      },
      userIds?: string[],
      platforms?: Array<"web" | "android" | "ios" | "harmony_os">
    },
    email?: { subject?: string, body?: string, attachments?: { filename?: string, content?: string, contentType?: string }[] },
    sms?:   { message?: string }
  },
  metadata?: { campaignId?: string, source?: string }
}

Champs minimum pour un push simple: { criticality: 1, channels: { push: { enabled: true } }, content: { push: { title, body } } }

2) Envoie Sms - Contrats

Permets l'envoi de SMS à un ou plusieurs numéros spécifiques.

Payload simplifié:

{
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,

channels: {
  sms: {
    enabled: boolean,
    recipients: string[],
  }
}
content: {
  sms: {
    message: string,
  }
}
metadata: {
  campaignId?: string,
  source?: string,
}
}

Cas d'usage rapide

{
  "criticality": 1,
  "messageId": "sms_2024_01_123",
  "correlationId": "1234567890",
  "channels": { 
      "sms": { 
          "enabled": true, 
          "recipients": ["+2250788364403"] 
      } 
  },
  "content": { 
      "sms": { 
          "message": "Code OTP: 123456" 
      } 
  },
  "metadata": {
    "campaignId": "CAM-001",
    "source": "eagence"
  }
}

3) Envoie Email - Contrats

Permets l'envoi d'email à un ou plusieurs destinataires spécifiques.

Payload simplifié:

{
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,

channels: {
  email: {
    enabled: boolean,
    recipients: string[],
  }
}
content: {
  email: {
    subject: string,
    body: string,
    attachments: { filename: string, content: string, contentType: string }[],
  }
}
metadata: {
  campaignId?: string,
  source?: string,
}
}

Cas d'usage rapide

{
  "criticality"   : 1,
  "messageId": "bill_2024_01_123",
  "correlationId": "1234567890",
  "channels": {
       "email": { 
          "enabled": true, 
          "recipients": ["client@example.com"] 
      } 
  },
  "content": { 
      "email": { 
          "subject": "Votre facture", 
          "body": "<p>Montant...</p>"
      } 
  },
  "metadata": {
    "campaignId": "CAM-001",
    "source": "eagence"
  }
}

4) Envoie Push - Contrats

Permets l'envoi de push à un ou plusieurs utilisateurs spécifiques.

a) Envoi ciblé par userIds (canaux: web, android, ios)

Payload simplifié:

{
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,

channels: {
  push: {
    enabled: boolean
  }
}
content: {
  push: {
    title: string,
    body: string,
    userIds: string[],
    platforms: string[], // android, ios, web
    data: {
      type: string,
      eventType: string,
      eventData: object,
    }
  }
}
metadata: {
  campaignId?: string,
  source?: string,
}
}

b) Broadcast par plateformes (android / ios / web)

Payload simplifié:

{
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,

channels: {
  push: {
    enabled: boolean
  }
}
content: {
  push: {
    title: string,
    body: string,
    platforms: string[], // android, ios, web
    data: {
      type: string,
      eventType: string,
      eventData: object,
    }
  }
}
metadata: {
  campaignId?: string,
  source?: string,
}
}

Cas d'usage rapide a) Push ciblé par userIds

{
  "criticality": 2,
  "messageId": "push_2024_01_123",
  "correlationId": "1234567890",
  "channels": { "push": { "enabled": true } },
  "content": { 
    "push": {
         "title": "Maj compte", 
         "body": "Votre compte est lié", 
         "userIds": ["user123"], 
         "platforms": ["android","ios","web"],
         data: { 
            "type": "functional_client", 
            "eventType": "level2_attachment", 
            "clientId": "CLI-001" 
        } 
    } 
  },
  "metadata": {
    "campaignId": "CAM-001",
    "source": "eagence"
  }
}

Cas d'usage rapide b) Broadcast par plateformes

{
    "criticality": 2,
    "messageId": "push_2024_01_123",
    "correlationId": "1234567890",
    "channels": { "push": { "enabled": true } },
    "content": { 
      push: {
           "title": "Maj compte", 
           "body": "Votre compte est lié", 
           "platforms": ["android", "web", "ios"],
           "data": { 
              "type": "functional_client", 
              "eventType": "level2_attachment", 
              "clientId": "CLI-001" 
          } 
      } 
    },
    "metadata": {
      "campaignId": "CAM-001",
      "source": "eagence"
    }
  }

5) Envoie sur tous les canaux - Contrats

Permets l'envoi de notification sur tous les canaux (push, email, sms).

Payload simplifié:

{
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,
channels: {
  push: {
    enabled: boolean
  },
  email: {
    enabled: boolean
  },
  sms: {
    enabled: boolean
  }
}
content: {
  push: {
    title: string,
    body: string,
    platforms: string[], // android, ios, web
    data: {
      type: string,
      eventType: string,
      eventData: object,
    }
  },
  email: {
    subject: string,
    body: string,
    attachments: { filename: string, content: string, contentType: string }[],
  }
  sms: {
    message: string,
  }
}
metadata: {
  campaignId?: string,
  source?: string,
}
}

Cas d'usage rapide sur tous les canaux

{
  "criticality": 2,
  "messageId": "push_2024_01_123",
  "correlationId": "1234567890",
  "channels": { 
    "push": { 
      "enabled": true 
    }, 
    "email": { 
      "enabled": true,
      "recipients": ["client@example.com"]
    },
    "sms": { 
      "enabled": true,
      "recipients": ["+22501020304"]
    } 
  },
  "content": { 
    "push": {
         "title": "Maj compte", 
         "body": "Votre compte est lié", 
         "userIds": ["CLI-001"], 
         "platforms": ["android","ios","web"],
         data: { 
            "type": "functional_client", 
            "eventType": "level2_attachment", 
            "clientId": "CLI-001" 
        } 
    },
    "email": {
      "subject": "Maj compte", 
      "body": "Votre compte est lié", 
    },
    "sms": {
      "message": "Votre compte est lié", 
    },
  },
  "metadata": {
    "campaignId": "CAM-001",
    "source": "eagence"
  }
}

7) Bonnes pratiques