Envoyer un message

Utilisez cette API pour envoyer des messages à un conversation_id spécifié et recevoir les réponses générées par l'agent. L'API prend en charge divers types de contenu de message, y compris le texte, les images, l'audio et les documents.

Méthode de requête

POST

Endpoint

https://api-${endpoint}.gptbots.ai/v2/conversation/message

Authentification

Consultez la section Présentation de l'API pour les instructions d'authentification.

Requête

Exemple de requête

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v2/conversation/message' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "conversation_id": "686e2646cb8ee942d9a62d79",
    "response_mode": "blocking",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "J'ai téléchargé 2 fichiers image, veuillez effectuer l'OCR et retourner 2 enregistrements json."
                },
                {
                    "type": "image",
                    "image": [
                        {
                            "base64_content": "<complete_base64_string>",
                            "format": "jpeg",
                            "name": "TAXI1"
                        },
                        {
                            "url": "https://gptbots.ai/example.png",
                            "format": "png",
                            "name": "TAXI2"
                        }
                    ]
                },
                {
                    "type": "audio",
                    "audio": [
                        {
                            "url": "https://gptbots.ai/example.mp3",
                            "format": "mp3",
                            "name": "exemple1 audio"
                        }
                    ]
                },
                {
                    "type": "document",
                    "document": [
                        {
                            "base64_content": "<complete_base64_string>",
                            "format": "pdf",
                            "name": "exemple pdf"
                        }
                    ]
                }
            ]
        }
    ],
    "conversation_config": {
        "long_term_memory": false,
        "short_term_memory": false,
        "knowledge": {
            "data_ids": [
                "58c70da0403cc812641b9356",
                "59c70da0403cc812641df35a"
            ],
            "group_ids": [
                "67c70da0403cc812641b93je",
                "69c70da0403cc812641df35f"
            ]
        },
        "custom_variables": {
            "var_current_url": "https://gptbots.ai/example",
            "var_session_id": "abcdef"
        }
    }
}'

                    

Remarques importantes :

1. Pour les types de contenu image, audio et document, vous pouvez utiliser soit l'encodage base64, soit des liens URL - les deux formats sont pris en charge.
2. En mode système de service client interne (Custom Helpdesk), les messages de l'agent et les messages utilisateur reçus pendant le transfert humain sont soumis avec ai_response=false ou role=human_agent ; ils sont uniquement archivés et ne déclenchent PAS l'IA. Exemple :
   { "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "blocking", "ai_response": false, "human_agent_info": { "name": "Alice", "email": "alice@example.com", "image_url": "https://gptbots.ai/avatar.png" }, "messages": [ { "role": "human_agent", "content": "Bonjour, ici le service client humain. Comment puis-je vous aider ?" } ] }

                         
                             {
           "conversation_id": "686e2646cb8ee942d9a62d79",
           "response_mode": "blocking",
           "ai_response": false,
           "human_agent_info": {
               "name": "Alice",
               "email": "alice@example.com",
               "image_url": "https://gptbots.ai/avatar.png"
           },
           "messages": [
               { "role": "human_agent", "content": "Bonjour, ici le service client humain. Comment puis-je vous aider ?" }
           ]
       }
   
                       

   Ce bloc de code dans la fenêtre flottante
3. Les développeurs n'ont besoin d'envoyer que le dernier message utilisateur, car GPTBots gère par défaut la mémoire à court et long terme. Si vous souhaitez personnaliser le contexte de la mémoire à court terme, consultez l'exemple ci-dessous :
   "messages": [ { "role": "user", "content": "Bonjour" //Mémoire à court terme personnalisée }, { "role": "assistant", "content": "Bonjour ! Comment puis-je vous aider aujourd'hui ?" //Mémoire à court terme personnalisée }, { "role": "user", "content": "Bonjour" //Dernier message utilisateur }]

                         
                             "messages": [
           {
               "role": "user", 
               "content": "Bonjour"                                //Mémoire à court terme personnalisée
           },
           {
               "role": "assistant",
               "content": "Bonjour ! Comment puis-je vous aider aujourd'hui ?"   //Mémoire à court terme personnalisée
           },
           {
               "role": "user",
               "content": "Bonjour"                                //Dernier message utilisateur
           }]
   
                       

   Ce bloc de code dans la fenêtre flottante
4. Lorsque les développeurs utilisent LoopAgent en mode streaming, s'ils ont besoin des messages de processus générés pendant l'exécution de l'agent, ils peuvent le déclarer via le champ de requête is_process_result.
   { "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "streaming", "is_process_result": true, "messages": [ { "role": "human_agent", "content": "Bonjour, ici le service client humain. Comment puis-je vous aider ?" } ] }

                         
                             {
           "conversation_id": "686e2646cb8ee942d9a62d79",
           "response_mode": "streaming",
           "is_process_result": true,
           "messages": [
               { "role": "human_agent", "content": "Bonjour, ici le service client humain. Comment puis-je vous aider ?" }
           ]
       }
   
                       

   Ce bloc de code dans la fenêtre flottante

En-têtes de requête

Paramètres de la requête

Note :

Les pages de configuration d'entrée et de sortie de l'agent prennent en charge différents schémas de reconnaissance pour différents types de messages. Les types et tailles de fichiers pris en charge varient. Adaptez les données de soumission API en conséquence. Formats de message pris en charge au maximum :

• Message texte : string
• Message audio : .mp3, .wav, .acc
• Message image : .jpg, .jpeg, .png, .gif, .webp
• Message document : .pdf, .txt, .docx, .csv, .xlsx, .html, .json, .md, .tex, .ts, .xml, etc.

Réponse

Exemple de réponse

                      
                      {
    "create_time": 1679587005,
    "conversation_id": "657303a8a764d47094874bbe",
    "user_id": "65a4ccfc7ce58e728d5897e0",
    "anonymous_id": "device_abcdef123456",
    "message_id": "65a4ccfC7ce58e728d5897e0",
    "output": [
        {
            "from_component_branch": "1",
            "from_component_name": "Nom du composant",
            "content": {
                "text": "Bonjour, puis-je vous aider ?",
                "audio": [
                    {
                        "audio": "http://gptbots.ai/example.mp3",
                        "transcript": "Contenu audio transcrit"
                    }
                ]
            }
        }
    ],
    "usage": {
        "tokens": {
            "total_tokens": 29,
            "prompt_tokens": 19,
            "prompt_tokens_details": {
                "audio_tokens": 0,
                "text_tokens": 0
            },
            "completion_tokens": 10,
            "completion_tokens_details": {
                "reasoning_tokens": 0,
                "audio_tokens": 0,
                "text_tokens": 0
            }
        },
        "credits": {
            "total_credits": 0.0,
            "text_input_credits": 0.0,
            "text_output_credits": 0.0,
            "audio_input_credits": 0.0,
            "audio_output_credits": 0.0
        }
    },
    "human_trigger": true
}

                    

Exemple de réponse lorsque le transfert humain est déclenché

En mode système de service client interne (Custom Helpdesk), lorsque cette réponse déclenche un transfert vers un agent humain, human_trigger vaut true ; si une note de transfert existe également, un objet handoff est renvoyé en plus (ce champ est absent lorsqu'il n'y a pas de note).

                      
                      {
    "create_time": 1679587005,
    "conversation_id": "657303a8a764d47094874bbe",
    "user_id": "65a4ccfc7ce58e728d5897e0",
    "anonymous_id": "device_abcdef123456",
    "message_id": "65a4ccfC7ce58e728d5897e0",
    "output": [
        {
            "from_component_branch": null,
            "from_component_name": "AI Model-1",
            "content": {
                "text": "Transfert vers un agent humain en cours, veuillez patienter.",
                "audio": null
            }
        }
    ],
    "usage": {
        "tokens": {
            "total_tokens": 29,
            "prompt_tokens": 19,
            "prompt_tokens_details": {
                "audio_tokens": 0,
                "text_tokens": 19
            },
            "completion_tokens": 10,
            "completion_tokens_details": {
                "reasoning_tokens": 0,
                "audio_tokens": 0,
                "text_tokens": 10
            }
        },
        "credits": {
            "total_credits": 0.0,
            "text_input_credits": 0.0,
            "text_output_credits": 0.0,
            "audio_input_credits": 0.0,
            "audio_output_credits": 0.0
        }
    },
    "human_trigger": true,
    "handoff": {
        "note": "Motif du transfert : l'utilisateur a exprimé à deux reprises son mécontentement à propos du processus de remboursement et a demandé une prise en charge par un agent humain.\nRésumé de la conversation : l'utilisateur a passé une commande le 2 mars, n'a pas reçu de notification de remboursement après avoir demandé un remboursement, et a confirmé le numéro de commande 20260302-8891."
    }
}

                    

Réponse réussie (Blocking)

⚠️ En mode de réponse blocking, le service de transfert humain n'est pas disponible lors de l'intégration de systèmes de service client humain tiers tels que LiveChat ou Intercom (les messages des agents sont envoyés de manière asynchrone et nécessitent le mode webhook pour être reçus).
Cette restriction ne s'applique pas lors de l'utilisation du système de service client interne (Custom Helpdesk) : le signal de transfert humain est renvoyé via human_trigger / handoff dans le corps de la réponse, et les messages des agents sont écrits par le développeur via cette même API avec role=human_agent.

Réponse réussie (Streaming)

⚠️ En mode de réponse streaming, le service de transfert humain n'est pas disponible lors de l'intégration de systèmes de service client humain tiers tels que LiveChat ou Intercom (les messages des agents sont envoyés de manière asynchrone et nécessitent le mode webhook pour être reçus).
Cette restriction ne s'applique pas lors de l'utilisation du système de service client interne (Custom Helpdesk) : le déclenchement du transfert humain est envoyé sous forme de trame code:36 HumanTrigger, et la note de transfert suit immédiatement sous forme de trame code:107 HumanHandoffNote.

• Exemple de streaming de message texte :

                      
                      {"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"Comment "}
{"code":3,"message":"Text","data":"puis "}
{"code":3,"message":"Text","data":"je "}
{"code":3,"message":"Text","data":"vous "}
{"code":3,"message":"Text","data":"aider ?"}
{"code":0,"message":"End","data":null}

                    

• Exemple de streaming de message audio :

                      
                      {"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"Bonjour"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":0,"message":"End","data":null}

                    

• Lorsqu'un transfert humain est déclenché en mode système de service client interne (Custom Helpdesk), la trame de déclenchement du transfert humain et la trame de note de transfert sont envoyées dans l'ordre, avant la trame End :

                      
                      {"code":3,"message":"Text","data":"Transfert vers un agent humain en cours, veuillez patienter."}
{"code":36,"message":"HumanTrigger","data":"HumanTrigger"}
{"code":107,"message":"HumanHandoffNote","data":{"note":"Motif du transfert : l'utilisateur a exprimé à deux reprises son mécontentement à propos du processus de remboursement et a demandé une prise en charge par un agent humain.\nRésumé de la conversation : l'utilisateur a passé une commande le 2 mars, n'a pas reçu de notification de remboursement après avoir demandé un remboursement, et a confirmé le numéro de commande 20260302-8891."}}
{"code":0,"message":"End","data":null}

                    

Remarque :

• code: 36, message: "HumanTrigger" indique que cette réponse a déclenché un transfert humain ; data est une chaîne d'identifiant fixe.
• code: 107, message: "HumanHandoffNote" correspond à la note de transfert ; sa structure data est identique au champ handoff de la réponse en mode blocking ({"note": "..."}).
• La trame HumanHandoffNote n'est envoyée que lorsqu'une note de transfert existe ; en l'absence de note, seule la trame HumanTrigger est présente — il n'y a pas de trame 107 vide.
• Les deux trames sont toujours envoyées avant la trame End (code: 0).

Réponse réussie (Webhook)

Une fois l'adresse du webhook configurée dans la section « Intégration-API », le système GPTBots enverra les messages « réponse de l'Agent » et « réponse du service client humain » à l'adresse du webhook.

Pour plus d'informations sur les messages webhook, veuillez consulter Réception de messages via Webhook et service de transfert humain.

⚠️ En mode API, si le service de transfert humain est activé, vous devez utiliser le mode de réponse webhook pour recevoir les messages de réponse du service client humain.

Réponse d'erreur

Exemple d'échec

                      
                      {
  "code": 40000,
  "message": "Paramètres invalides",
  "errors": [
    {
      "error_code": 40000,
      "error_message": "Message user role type must have file or content."
    }
  ],
  "data": {
    "create_time": 1679587005,
    "conversation_id": "657303a8a764d47094874bbe",
    "user_id": "65a4ccfc7ce58e728d5897e0",
    "anonymous_id": "device_abcdef123456",
    "message_id": "65a4ccfC7ce58e728d5897e0",
    "output": [
      {
        "from_component_branch": "1",
        "from_component_name": "Component Name",
        "content": {
          "text": "Réponse fournie en fonction du contenu reconnaissable……",
          "audio": null
        }
      }
    ],
    "usage": {
      "tokens": {
        "total_tokens": 29,
        "prompt_tokens": 19,
        "prompt_tokens_details": {
          "audio_tokens": 0,
          "text_tokens": 0
        },
        "completion_tokens": 10,
        "completion_tokens_details": {
          "reasoning_tokens": 0,
          "audio_tokens": 0,
          "text_tokens": 0
        }
      },
      "credits": {
        "total_credits": 0,
        "text_input_credits": 0,
        "text_output_credits": 0,
        "audio_input_credits": 0,
        "audio_output_credits": 0
      }
    }
  }
}

                    

Codes d'erreur