#include <pipecat/client.h>

Public Member Functions
	PipecatClient (PipecatClientOptions options)
	Creates a client. Throws PipecatError if there's no transport.

	~PipecatClient ()
	Disconnects, and runs the callbacks still waiting, before returning.

	PipecatClient (const PipecatClient &)=delete
	Clients can't be copied.

PipecatClient &	operator= (const PipecatClient &)=delete
	Clients can't be copied.

Connection
void	initialize ()

nlohmann::json	start_bot (const APIRequest &request)

rtvi::BotReadyData	connect (const nlohmann::json &transport_params=nullptr)

rtvi::BotReadyData	start_bot_and_connect (const APIRequest &request)

void	disconnect ()

TransportState	state () const
	The connection state.

bool	connected () const
	Whether the client is connected, even if the bot isn't ready yet.

Transport &	transport ()

Audio
int32_t	send_user_audio (const int16_t *frames, size_t num_frames)

int32_t	read_bot_audio (int16_t *frames, size_t num_frames)

Messages to the bot
void	send_text (const std::string &content, const rtvi::SendTextOptions &options={})
	Sends text to the bot's LLM, as if the user said it.

void	send_client_message (const std::string &type, const nlohmann::json &data=nullptr)
	Sends an app-defined message to the bot.

void	disconnect_bot ()
	Asks the bot to leave. The client stays connected.

void	send_dtmf (const std::string &buttons)

Client requests
void	send_client_request (const std::string &type, const nlohmann::json &data, ClientResponseCallback callback, std::chrono::milliseconds timeout=std::chrono::seconds(10))

std::future< nlohmann::json >	send_client_request (const std::string &type, const nlohmann::json &data=nullptr, std::chrono::milliseconds timeout=std::chrono::seconds(10))

Detailed Description

Connects to a Pipecat bot through a transport.

All methods are thread-safe. start_bot(), connect() and disconnect() return once they're done. Everything else returns right away.

Sending messages needs a ready bot. Otherwise it throws BotNotReadyError. Messages too large for the transport throw MessageTooLargeError.

Member Function Documentation

◆ connect()

rtvi::BotReadyData pipecat::PipecatClient::connect ( const nlohmann::json & transport_params = nullptr )

Connects to the bot and waits until it's ready.

transport_params tell the transport how to reach the bot, like a room URL and a token. They usually come from start_bot(), but you can also get them another way, e.g. from your backend. Their format depends on the transport.

Throws BotAlreadyStartedError, ConnectionTimeoutError or the transport's errors, and disconnects if it fails.

◆ disconnect()

void pipecat::PipecatClient::disconnect ( )

Disconnects from the bot and returns once disconnected, also when another disconnection is already in progress.

If start_bot() or connect() are still running, they stop and throw. If the transport is still connecting, this first waits until it's done.

◆ initialize()

void pipecat::PipecatClient::initialize ( )

Prepares the transport, e.g. its audio devices. Optional: start_bot() and connect() do it when needed.

◆ read_bot_audio()

int32_t pipecat::PipecatClient::read_bot_audio	(	int16_t *	frames,
		size_t	num_frames
	)

Reads up to num_frames frames of 16-bit PCM bot audio into frames. Returns the number of frames read, or 0 if not connected.

◆ send_client_request() [1/2]

void pipecat::PipecatClient::send_client_request	(	const std::string &	type,
		const nlohmann::json &	data,
		ClientResponseCallback	callback,
		std::chrono::milliseconds	timeout = `std::chrono::seconds(10)`
	)

Sends an app-defined message to the bot, and calls callback with its answer.

callback runs on the client's own thread, like callbacks. The request fails if the bot doesn't answer within timeout. Zero waits forever.

◆ send_client_request() [2/2]

std::future< nlohmann::json > pipecat::PipecatClient::send_client_request	(	const std::string &	type,
		const nlohmann::json &	data = `nullptr`,
		std::chrono::milliseconds	timeout = `std::chrono::seconds(10)`
	)

Sends an app-defined message to the bot, and returns its answer.

The future's get() throws MessageError if the request fails, and RequestTimeoutError if the bot doesn't answer within timeout. Zero waits forever. You can wait for the answer inside a callback.

◆ send_dtmf()

void pipecat::PipecatClient::send_dtmf ( const std::string & buttons )

Sends DTMF keys (0-9, * and #), e.g. "123#".

Throws PipecatError if buttons has other characters, and UnsupportedFeatureError if the bot uses an RTVI version older than 2.1.

◆ send_user_audio()

int32_t pipecat::PipecatClient::send_user_audio	(	const int16_t *	frames,
		size_t	num_frames
	)

Sends num_frames frames of 16-bit PCM user audio to the bot. Returns the number of frames sent, or 0 if not connected.

◆ start_bot()

nlohmann::json pipecat::PipecatClient::start_bot ( const APIRequest & request )

Starts a bot.

Sends request to a start endpoint, like Pipecat Cloud or your own server. The endpoint starts a bot and answers with what the transport needs to reach it, like a room URL and a token. Pass that answer to connect().

You don't need this if your app already knows how to reach the bot. Throws BotAlreadyStartedError or StartBotError.

◆ start_bot_and_connect()

rtvi::BotReadyData pipecat::PipecatClient::start_bot_and_connect ( const APIRequest & request )

Starts a bot and connects to it: start_bot(), then connect() with its answer.

◆ transport()

Transport & pipecat::PipecatClient::transport ( )

The transport, e.g. to use its own features. Connect and disconnect with the client, not the transport.

The documentation for this class was generated from the following file:

pipecat/client.h

Public Member Functions