go-tdlib

The NewClient function accepts variadic Option arguments to customize the client. Use the following functions to configure your instance:

• WithExtraGenerator(extraGenerator ExtraGenerator): Sets a custom generator for request extra IDs.
• WithFallbackTimeout(timeout time.Duration): Sets the maximum time the client will wait for a response before returning a timeout error if the provided context is still active.
• WithProxy(req *AddProxyRequest): Configures a proxy for the client connection.
• WithResultHandler(resultHandler ResultHandler): Sets a custom handler for all incoming updates/results.

client, err := client.NewClient(
	authHandler,
	client.WithFallbackTimeout(60 * time.Second),
	client.WithResultHandler(myResultHandler),
)

Use Send(ctx context.Context, req Request) to send a request to TDLib and wait for the specific response associated with that request.

This method is synchronous in terms of the caller's flow: it waits for the response to arrive, or for the provided ctx to expire, or for the client's internal fallbackTimeout to be reached.

• Context: The ctx allows you to cancel the request from the caller side.
• Fallback: If the response doesn't arrive within client.fallbackTimeout, an error is returned.
• Extra IDs: The method automatically handles request tracking using an ExtraGenerator.

resp, err := client.Send(ctx, myRequest)
if err != nil {
	// Handle error (timeout, context cancellation, etc.)
}
// Use resp.Data to access the result

Use Execute(req Request) to send a request to TDLib. Unlike Send, Execute does not wait for a specific response via the internal response channel mechanism; it relies on the underlying jsonClient.Execute implementation. Use this when you do not need the specific request-response correlation provided by Send.

resp, err := client.Execute(myRequest)

To react to asynchronous updates (like new messages or authorization state changes) sent by TDLib, implement the ResultHandler interface and pass it to NewClient via WithResultHandler.

type MyHandler struct{}

func (h *MyHandler) OnResult(result client.Type) {
	// Handle the incoming TDLib type
}

Alternatively, you can use the helper NewCallbackResultHandler to pass a simple callback function:

handler := client.NewCallbackResultHandler(func(result client.Type) {
	fmt.Printf("Received: %v\n", result)
})
// Pass this handler to NewClient via WithResultHandler

handler := client.NewCallbackResultHandler(func(result client.Type) {
	fmt.Println("Received update")
})

Use NewClient to create a new TDLib client instance. This function requires an AuthorizationStateHandler to manage the Telegram authorization lifecycle and accepts optional Option functions to configure the client behavior.

Note that NewClient internally calls Authorize, so the provided authorizationStateHandler must be able to handle the necessary authorization steps (like entering phone numbers or codes) to successfully establish a session.

client, err := client.NewClient(authorizationStateHandler, client.WithFallbackTimeout(30 * time.Second))