messages.h

Go to the documentation of this file.

//
// Copyright (c) 2024-2026, Daily
//
// SPDX-License-Identifier: BSD-2-Clause
//
 
 
#ifndef PIPECAT_RTVI_MESSAGES_H
#define PIPECAT_RTVI_MESSAGES_H
 
#include <nlohmann/json.hpp>
 
#include <cstdint>
#include <optional>
#include <string>
#include <vector>
 
namespace pipecat::rtvi {
 
inline constexpr const char* PROTOCOL_VERSION = "2.1.0";
 
inline constexpr const char* MESSAGE_LABEL = "rtvi-ai";
 
enum class MessageType {
    // Client to server.
    ClientReady,            
    DisconnectBot,          
    ClientMessage,          
    SendText,               
    DTMF,                   
    LLMFunctionCallResult,  
 
    // Server to client.
    BotReady,                   
    Error,                      
    ErrorResponse,              
    ServerMessage,              
    ServerResponse,             
    Metrics,                    
    UserStartedSpeaking,        
    UserStoppedSpeaking,        
    BotStartedSpeaking,         
    BotStoppedSpeaking,         
    BotInterrupted,             
    UserMuteStarted,            
    UserMuteStopped,            
    UserTranscription,          
    UserLLMText,                
    BotOutput,                  
    BotLLMText,                 
    BotLLMStarted,              
    BotLLMStopped,              
    BotLLMSearchResponse,       
    BotTTSText,                 
    BotTTSStarted,              
    BotTTSStopped,              
    LLMFunctionCallStarted,     
    LLMFunctionCallInProgress,  
    LLMFunctionCallStopped,     
};
 
const char* to_string(MessageType type);
 
std::optional<MessageType> parse_message_type(const std::string& type);
 
struct AboutClientData {
    std::string library;
    std::optional<std::string> library_version;
    std::optional<std::string> platform;
    std::optional<std::string> platform_version;
    nlohmann::json platform_details;
};
 
AboutClientData default_about_client();
 
struct ClientMessageData {
    std::string type;
    nlohmann::json data;
};
 
struct SendTextOptions {
    std::optional<bool> run_immediately;
    std::optional<bool> audio_response;
};
 
struct LLMFunctionCallResultData {
    std::string function_name;
    std::string tool_call_id;
    nlohmann::json arguments;
    nlohmann::json result;
};
 
struct BotReadyData {
    std::string version;
    nlohmann::json about;
};
 
struct ErrorData {
    std::string error;
    bool fatal = false;
};
 
struct TranscriptData {
    std::string text;
    bool final = false;
    std::string timestamp;
    std::string user_id;
};
 
struct TextData {
    std::string text;
};
 
using UserLLMTextData = TextData;
 
using BotLLMTextData = TextData;
 
using BotTTSTextData = TextData;
 
struct SpokenProgressData {
    std::string accumulated_text;
    std::string remaining_text;
};
 
struct BotOutputData {
    std::string text;
    std::string aggregated_by;
    std::optional<int64_t> segment_id;
    std::optional<bool> will_be_spoken;
    std::optional<std::string> spoken_status;
    std::optional<SpokenProgressData> spoken_progress;
};
 
struct MetricData {
    std::string processor;
    std::optional<std::string> model;
    double value = 0;
};
 
struct MetricsData {
    std::vector<MetricData> ttfb;
    std::vector<MetricData> processing;
    std::vector<MetricData> characters;
    nlohmann::json raw;
};
 
struct LLMFunctionCallStartedData {
    std::optional<std::string> function_name;
};
 
struct LLMFunctionCallInProgressData {
    std::optional<std::string> function_name;
    std::string tool_call_id;
    nlohmann::json arguments;
};
 
struct LLMFunctionCallStoppedData {
    std::optional<std::string> function_name;
    std::string tool_call_id;
    bool cancelled = false;
    nlohmann::json result;
};
 
struct LLMSearchResult {
    std::string text;
    std::vector<double> confidence;
};
 
struct LLMSearchOrigin {
    std::optional<std::string> site_uri;
    std::optional<std::string> site_title;
    std::vector<LLMSearchResult> results;
};
 
struct BotLLMSearchResponseData {
    std::optional<std::string> search_result;
    std::optional<std::string> rendered_content;
    std::vector<LLMSearchOrigin> origins;
};
 
struct Message {
    std::string id;
    std::string label = MESSAGE_LABEL;
    std::string type;
    nlohmann::json data;
 
    Message() = default;
 
    explicit Message(MessageType type, nlohmann::json data = nullptr);
 
    static Message client_ready(const AboutClientData& about);
 
    static Message disconnect_bot();
 
    static Message
    client_message(const std::string& type, const nlohmann::json& data);
 
    static Message
    send_text(const std::string& content, const SendTextOptions& options = {});
 
    static Message dtmf(const std::string& buttons);
 
    static Message llm_function_call_result(
            const LLMFunctionCallResultData& data
    );
};
 
//
// JSON conversions, used by nlohmann::json (e.g. `data.get<BotOutputData>()`).
//
 
 
void to_json(nlohmann::json& j, const Message& message);
void from_json(const nlohmann::json& j, Message& message);
 
void to_json(nlohmann::json& j, const AboutClientData& data);
void to_json(nlohmann::json& j, const SendTextOptions& options);
void to_json(nlohmann::json& j, const LLMFunctionCallResultData& data);
 
void to_json(nlohmann::json& j, const ClientMessageData& data);
void from_json(const nlohmann::json& j, ClientMessageData& data);
 
void from_json(const nlohmann::json& j, BotReadyData& data);
void from_json(const nlohmann::json& j, ErrorData& data);
void from_json(const nlohmann::json& j, TranscriptData& data);
void from_json(const nlohmann::json& j, TextData& data);
void from_json(const nlohmann::json& j, SpokenProgressData& data);
void from_json(const nlohmann::json& j, BotOutputData& data);
void from_json(const nlohmann::json& j, MetricData& data);
void from_json(const nlohmann::json& j, MetricsData& data);
void from_json(const nlohmann::json& j, LLMFunctionCallStartedData& data);
void from_json(const nlohmann::json& j, LLMFunctionCallInProgressData& data);
void from_json(const nlohmann::json& j, LLMFunctionCallStoppedData& data);
void from_json(const nlohmann::json& j, LLMSearchResult& data);
void from_json(const nlohmann::json& j, LLMSearchOrigin& data);
void from_json(const nlohmann::json& j, BotLLMSearchResponseData& data);
 
 
}  // namespace pipecat::rtvi
 
#endif