Pipecat C++ Client SDK 1.3.0
Connect native apps to Pipecat bots
Loading...
Searching...
No Matches
client.h
Go to the documentation of this file.
1//
2// Copyright (c) 2024-2026, Daily
3//
4// SPDX-License-Identifier: BSD-2-Clause
5//
6
9
10#ifndef PIPECAT_CLIENT_H
11#define PIPECAT_CLIENT_H
12
14#include "pipecat/transport.h"
15
16#include <nlohmann/json.hpp>
17
18#include <chrono>
19#include <cstddef>
20#include <cstdint>
21#include <functional>
22#include <future>
23#include <map>
24#include <memory>
25#include <optional>
26#include <string>
27
29namespace pipecat {
30
35using FunctionCallResultCallback = std::function<void(nlohmann::json result)>;
36
44 public:
45 virtual ~PipecatClientCallbacks() = default;
46
49
51 virtual void on_transport_state_changed(TransportState /* state */) {}
52
54 virtual void on_connected() {}
55
57 virtual void on_disconnected() {}
58
61 virtual void on_error(const rtvi::ErrorData& /* error */) {}
62
64
67
69 virtual void on_bot_started(const nlohmann::json& /* response */) {}
70
72 virtual void on_bot_connected(const Participant& /* bot */) {}
73
75 virtual void on_bot_ready(const rtvi::BotReadyData& /* data */) {}
76
78 virtual void on_bot_disconnected(const Participant& /* bot */) {}
79
81 virtual void on_participant_joined(const Participant& /* participant */) {}
82
84 virtual void on_participant_left(const Participant& /* participant */) {}
85
87
90
92 virtual void on_server_message(const nlohmann::json& /* data */) {}
93
95 virtual void on_message_error(const rtvi::ErrorData& /* error */) {}
96
98 virtual void on_metrics(const rtvi::MetricsData& /* data */) {}
99
102 virtual void on_unhandled_message(const rtvi::Message& /* message */) {}
103
105
108
110 virtual void on_user_started_speaking() {}
111
113 virtual void on_user_stopped_speaking() {}
114
116 virtual void on_bot_started_speaking() {}
117
119 virtual void on_bot_stopped_speaking() {}
120
123 virtual void on_bot_interrupted() {}
124
127 virtual void on_user_mute_started() {}
128
130 virtual void on_user_mute_stopped() {}
131
133
136
139 virtual void on_user_input(const rtvi::UserInputData& /* data */) {}
140
142 virtual void on_user_llm_text(const rtvi::UserLLMTextData& /* data */) {}
143
145 virtual void on_bot_output(const rtvi::BotOutputData& /* data */) {}
146
148
151
155 virtual void on_stt_raw_text(const rtvi::STTRawTextData& /* data */) {}
156
158
161
163 virtual void on_bot_llm_started() {}
164
166 virtual void on_bot_llm_stopped() {}
167
171 virtual void on_llm_raw_text(const rtvi::LLMRawTextData& /* data */) {}
172
175 const rtvi::BotLLMSearchResponseData& /* data */
176 ) {}
177
179
182
185 const rtvi::LLMFunctionCallStartedData& /* data */
186 ) {}
187
193 const rtvi::LLMFunctionCallInProgressData& /* data */,
194 FunctionCallResultCallback /* respond */
195 ) {}
196
199 const rtvi::LLMFunctionCallStoppedData& /* data */
200 ) {}
201
203
206
208 virtual void on_bot_tts_started() {}
209
211 virtual void on_bot_tts_stopped() {}
212
216 virtual void on_tts_raw_text(const rtvi::TTSRawTextData& /* data */) {}
217
219};
220
225 std::string endpoint;
227 std::map<std::string, std::string> headers;
229 nlohmann::json request_data;
231 std::chrono::milliseconds timeout {0};
232};
233
237 nlohmann::json data;
239 std::optional<std::string> error;
241 bool timed_out = false;
242};
243
245using ClientResponseCallback = std::function<void(const ClientResponse&)>;
246
250 std::unique_ptr<Transport> transport;
256 std::chrono::milliseconds connect_timeout = std::chrono::seconds(30);
260};
261
270 public:
273
276
278 PipecatClient(const PipecatClient&) = delete;
279
282
285
289
299 nlohmann::json start_bot(const APIRequest& request);
300
311 const nlohmann::json& transport_params = nullptr
312 );
313
317
324
327
329 bool connected() const;
330
334
336
339
342 int32_t send_user_audio(const int16_t* frames, size_t num_frames);
343
346 int32_t read_bot_audio(int16_t* frames, size_t num_frames);
347
349
352
357 std::string send_text(
358 const std::string& content,
359 const rtvi::SendTextOptions& options = {}
360 );
361
364 const std::string& type,
365 const nlohmann::json& data = nullptr
366 );
367
370
375 void send_dtmf(const std::string& buttons);
376
378
381
388 const std::string& type,
389 const nlohmann::json& data,
390 ClientResponseCallback callback,
391 std::chrono::milliseconds timeout = std::chrono::seconds(10)
392 );
393
399 std::future<nlohmann::json> send_client_request(
400 const std::string& type,
401 const nlohmann::json& data = nullptr,
402 std::chrono::milliseconds timeout = std::chrono::seconds(10)
403 );
404
406
407 private:
408 class Impl;
409 std::unique_ptr<Impl> _impl;
410};
411
412} // namespace pipecat
413
414#endif
Definition client.h:43
virtual void on_disconnected()
The client disconnected.
Definition client.h:57
virtual void on_llm_function_call_started(const rtvi::LLMFunctionCallStartedData &)
The bot's LLM started a function call.
Definition client.h:184
virtual void on_bot_connected(const Participant &)
The bot joined the session.
Definition client.h:72
virtual void on_bot_interrupted()
Definition client.h:123
virtual void on_bot_ready(const rtvi::BotReadyData &)
The bot is ready to talk.
Definition client.h:75
virtual void on_connected()
The client connected. The bot isn't ready yet, see on_bot_ready().
Definition client.h:54
virtual void on_stt_raw_text(const rtvi::STTRawTextData &)
Definition client.h:155
virtual void on_bot_tts_started()
The bot's text-to-speech started.
Definition client.h:208
virtual void on_message_error(const rtvi::ErrorData &)
The bot couldn't handle a message from the client.
Definition client.h:95
virtual void on_user_input(const rtvi::UserInputData &)
Definition client.h:139
virtual void on_bot_llm_started()
The bot's LLM started responding.
Definition client.h:163
virtual void on_bot_tts_stopped()
The bot's text-to-speech stopped.
Definition client.h:211
virtual void on_user_started_speaking()
The user started speaking.
Definition client.h:110
virtual void on_bot_disconnected(const Participant &)
The bot left the session.
Definition client.h:78
virtual void on_bot_output(const rtvi::BotOutputData &)
What the bot says or outputs.
Definition client.h:145
virtual void on_bot_llm_search_response(const rtvi::BotLLMSearchResponseData &)
Search results used by the bot's LLM.
Definition client.h:174
virtual void on_user_llm_text(const rtvi::UserLLMTextData &)
User text was sent to the bot's LLM.
Definition client.h:142
virtual void on_metrics(const rtvi::MetricsData &)
The bot sent performance metrics.
Definition client.h:98
virtual void on_bot_started(const nlohmann::json &)
The bot was started. response is what the start endpoint answered.
Definition client.h:69
virtual void on_tts_raw_text(const rtvi::TTSRawTextData &)
Definition client.h:216
virtual void on_llm_raw_text(const rtvi::LLMRawTextData &)
Definition client.h:171
virtual void on_bot_stopped_speaking()
The bot stopped speaking.
Definition client.h:119
virtual void on_server_message(const nlohmann::json &)
The bot sent an app-defined message.
Definition client.h:92
virtual void on_participant_joined(const Participant &)
Someone other than the bot joined the session.
Definition client.h:81
virtual void on_error(const rtvi::ErrorData &)
Definition client.h:61
virtual void on_llm_function_call_in_progress(const rtvi::LLMFunctionCallInProgressData &, FunctionCallResultCallback)
Definition client.h:192
virtual void on_unhandled_message(const rtvi::Message &)
Definition client.h:102
virtual void on_bot_llm_stopped()
The bot's LLM finished responding.
Definition client.h:166
virtual void on_user_mute_stopped()
The bot stopped ignoring user audio.
Definition client.h:130
virtual void on_llm_function_call_stopped(const rtvi::LLMFunctionCallStoppedData &)
A function call finished or was cancelled.
Definition client.h:198
virtual void on_user_stopped_speaking()
The user stopped speaking.
Definition client.h:113
virtual void on_participant_left(const Participant &)
Someone other than the bot left the session.
Definition client.h:84
virtual void on_user_mute_started()
Definition client.h:127
virtual void on_transport_state_changed(TransportState)
The connection state changed.
Definition client.h:51
virtual void on_bot_started_speaking()
The bot started speaking.
Definition client.h:116
Definition client.h:269
int32_t read_bot_audio(int16_t *frames, size_t num_frames)
rtvi::BotReadyData connect(const nlohmann::json &transport_params=nullptr)
~PipecatClient()
Disconnects, and runs the callbacks still waiting, before returning.
void send_dtmf(const std::string &buttons)
rtvi::BotReadyData start_bot_and_connect(const APIRequest &request)
PipecatClient(const PipecatClient &)=delete
Clients can't be copied.
TransportState state() const
The connection state.
Transport & transport()
std::string send_text(const std::string &content, const rtvi::SendTextOptions &options={})
void send_client_message(const std::string &type, const nlohmann::json &data=nullptr)
Sends an app-defined message to the bot.
int32_t send_user_audio(const int16_t *frames, size_t num_frames)
void send_client_request(const std::string &type, const nlohmann::json &data, ClientResponseCallback callback, std::chrono::milliseconds timeout=std::chrono::seconds(10))
PipecatClient & operator=(const PipecatClient &)=delete
Clients can't be copied.
std::future< nlohmann::json > send_client_request(const std::string &type, const nlohmann::json &data=nullptr, std::chrono::milliseconds timeout=std::chrono::seconds(10))
void disconnect_bot()
Asks the bot to leave. The client stays connected.
bool connected() const
Whether the client is connected, even if the bot isn't ready yet.
PipecatClient(PipecatClientOptions options)
Creates a client. Throws PipecatError if there's no transport.
nlohmann::json start_bot(const APIRequest &request)
Definition transport.h:91
AboutClientData default_about_client()
Information about this library and the platform it runs on.
The Pipecat C++ client SDK.
Definition client.h:29
TransportState
The state of the connection to the bot.
Definition transport.h:26
std::function< void(const ClientResponse &)> ClientResponseCallback
Receives the bot's answer to a request.
Definition client.h:245
std::function< void(nlohmann::json result)> FunctionCallResultCallback
Definition client.h:35
Definition client.h:223
std::string endpoint
URL of the start endpoint.
Definition client.h:225
std::chrono::milliseconds timeout
How long to wait for an answer. Zero waits forever.
Definition client.h:231
std::map< std::string, std::string > headers
HTTP headers, e.g. for authentication.
Definition client.h:227
nlohmann::json request_data
JSON body of the request. Null sends no body.
Definition client.h:229
The bot's answer to a request.
Definition client.h:235
std::optional< std::string > error
Why the request failed, if it did.
Definition client.h:239
bool timed_out
Whether the request failed because the bot didn't answer in time.
Definition client.h:241
nlohmann::json data
What the bot answered. Null if the request failed.
Definition client.h:237
Someone in the session, like the bot or another user.
Definition transport.h:43
Options to create a PipecatClient.
Definition client.h:248
std::unique_ptr< Transport > transport
The transport to connect with. Required.
Definition client.h:250
rtvi::AboutClientData about
Definition client.h:259
bool disconnect_on_bot_disconnect
Whether to disconnect when the bot leaves.
Definition client.h:254
PipecatClientCallbacks * callbacks
Receives events. Optional, and must outlive the client.
Definition client.h:252
std::chrono::milliseconds connect_timeout
How long connect() waits for the bot to be ready. Zero waits forever.
Definition client.h:256
Information about the client, sent to the bot when connecting.
Definition messages.h:84
Search results used by the bot's LLM.
Definition messages.h:366
Definition messages.h:265
Sent by the bot when it's ready.
Definition messages.h:148
An error.
Definition messages.h:159
A function call is running.
Definition messages.h:325
The bot's LLM started a function call.
Definition messages.h:319
A function call finished or was cancelled.
Definition messages.h:336
Definition messages.h:379
Performance metrics from the bot.
Definition messages.h:307
A transcription, as the bot's speech-to-text made it.
Definition messages.h:224
Options for sending text to the bot.
Definition messages.h:109
Some text.
Definition messages.h:239
What the user said or typed.
Definition messages.h:195