client

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 29, 2024 License: MIT Imports: 14 Imported by: 0

README

Gradient Labs Go

Go Reference

Go bindings for the Gradient Labs API.

Documentation

Overview

Package client implements Go bindings for the Gradient Labs API.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidWebhookSignature is returned when the authenticity of the webhook
	// could not be verified using its signature. You should respond with an HTTP
	// 401 status code.
	ErrInvalidWebhookSignature = fmt.Errorf("%s header is invalid", signatureHeader)

	// ErrUnknownWebhookType is returned when the webhook contained an event of an
	// unknwon type. You should generally log these and return an HTTP 200 status
	// code.
	ErrUnknownWebhookType = errors.New("unknown webhook type")
)

Functions

This section is empty.

Types

type AddMessageParams 

type AddMessageParams struct {
	// ID uniquely identifies this message within the conversation.
	//
	// Can be anything consisting of letters, numbers, or any of the following
	// characters: _ - + =.
	//
	// Tip: use something meaningful to your business.
	ID string `json:"id"`

	// Body contains the message text.
	Body string `json:"body"`

	// ParticipantID identifies the message sender.
	ParticipantID string `json:"participant_id"`

	// ParticipantType identifies the type of participant who sent this message.
	ParticipantType ParticipantType `json:"participant_type"`

	// Created is the time at which the message was sent.
	Created time.Time `json:"created"`

	// Metadata is arbitrary metadata that will be attached to the message.
	Metadata any `json:"metadata"`
}

AddMessageParams are the parameters to Client.AddMessage.

type AgentMessageEvent 

type AgentMessageEvent struct {
	// Conversation contains the details of the conversation the event relates to.
	Conversation WebhookConversation `json:"conversation"`

	// Body contains the text of the message the agent wants to send.
	Body string `json:"body"`
}

AgentMessageEvent contains the data for an `agent.message` webhook event.

type Channel 

type Channel string

Channel represents the way a customer is getting in touch. It will be used to determine how the agent formats responses, etc. 

const (
	// ChannelWeb indicates the customer is getting in touch via a live instant
	// message chat.
	ChannelWeb Channel = "web"

	// ChannelEmail indicates the customer is getting in touch via an email.
	ChannelEmail Channel = "email"
)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides access to the Gradient Labs API. Use NewClient to create one.

func NewClient 

func NewClient(opts ...Option) (*Client, error)

NewClient creates a client with the given options.

Note: the WithAPIKey option is required, as is WithWebhookSigningKey if you intend to receive webhooks.

func (*Client) AddMessage 

func (c *Client) AddMessage(ctx context.Context, conversationID string, p AddMessageParams) (*Message, error)

AddMessage records a message sent by the customer or a human agent.

func (*Client) CancelConversation 

func (c *Client) CancelConversation(ctx context.Context, conversationID string) error

CancelConversation cancels a conversation to abruptly stop the agent responding (e.g. because a human agent has taken over).

func (*Client) ParseWebhook 

func (c *Client) ParseWebhook(req *http.Request) (*Webhook, error)

ParseWebhook parses the request, verifies its signature, and returns the webhook data.

func (*Client) StartConversation 

func (c *Client) StartConversation(ctx context.Context, p StartConversationParams) (*Conversation, error)

StartConversation begins a conversation with the agent.

func (*Client) VerifyWebhookRequest 

func (c *Client) VerifyWebhookRequest(req *http.Request) error

VerifyWebhookRequest verifies the authenticity of the given request using its signature header. You do not need to call it if you're already using Client.ParseWebhook.

type Conversation 

type Conversation struct {
	// ID uniquely identifies the conversation.
	//
	// Can be anything consisting of letters, numbers, or any of the following
	// characters: _ - + =.
	//
	// Tip: use something meaningful to your business (e.g. a ticket number).
	ID string `json:"id"`

	// CustomerID uniquely identifies the customer. Used to build historical
	// context of conversations the agent has had with this customer.
	CustomerID string `json:"customer_id"`

	// Channel represents the way a customer is getting in touch. It will be used
	// to determine how the agent formats responses, etc.
	Channel Channel `json:"channel"`

	// Metadata is arbitrary metadata that will be attached to the conversation.
	// It will be passed along with webhooks so can be used as action parameters.
	Metadata any `json:"metadata"`

	// Created is the time at which the conversation was created.
	Created time.Time `json:"created"`

	// Updated is the time at which the conversation was last updated.
	Updated time.Time `json:"updated"`

	// Status describes the current state of the conversation.
	Status Status `json:"status"`
}

Conversation represents a series of messages between a customer, human agent, and the AI Agent.

type ConversationFinishedEvent 

type ConversationFinishedEvent struct {
	// Conversation contains the details of the conversation the event relates to.
	Conversation WebhookConversation `json:"conversation"`
}

ConversationFinishedEvent contains the data for a `conversation.finished` event.

type ConversationHandOffEvent 

type ConversationHandOffEvent struct {
	// Conversation contains the details of the conversation the event relates to.
	Conversation WebhookConversation `json:"conversation"`
}

ConversationHandOffEvent contains the data for a `conversation.hand_off` event.

type Message 

type Message struct {
	// ID uniquely identifies this message within the conversation.
	//
	// Can be anything consisting of letters, numbers, or any of the following
	// characters: _ - + =.
	//
	// Tip: use something meaningful to your business.
	ID string `json:"id"`

	// Body contains the message text.
	Body string `json:"body"`

	// ParticipantID identifies the message sender.
	ParticipantID string `json:"participant_id"`

	// ParticipantType identifies the type of participant who sent this message.
	ParticipantType ParticipantType `json:"participant_type"`

	// Created is the time at which the message was sent.
	Created time.Time `json:"created"`

	// Metadata is arbitrary metadata attached to the message.
	Metadata any `json:"metadata"`
}

Message represents a message sent by a customer, human support agent, or the API agent.

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option customises the Client.

func WithAPIKey 

func WithAPIKey(key string) Option

WithAPIKey sets the client's API key.

func WithTransport 

func WithTransport(rt http.RoundTripper) Option

WithTransport customises the HTTP client's Transport, which is useful for observability (e.g. capturing trace spaces, metrics) and in unit tests.

func WithURL 

func WithURL(url string) Option

WithURL overrides the default base URL.

func WithWebhookLeeway 

func WithWebhookLeeway(leeway time.Duration) Option

WithWebhookLeeway determines the maximum age of webhook that will be accepted by Client.VerifyWebhookRequest.

func WithWebhookSigningKey 

func WithWebhookSigningKey(key string) Option

WithWebhookSigningKey sets the client's webhook signing key. It will be used to verify webhook authenticity.

type ParticipantType 

type ParticipantType string

ParticipantType identifies the type of participant who sent a message. 

const (
	// ParticipantTypeCustomer indicates that the message was sent by a
	// customer/end-user.
	ParticipantTypeCustomer ParticipantType = "Customer"

	// ParticipantTypeAgent indicates that the message was sent by a human support
	// agent.
	ParticipantTypeAgent ParticipantType = "Agent"

	// ParticipantTypeBot indicates that the message was sent by an automation/bot
	// other than the Gradient Labs AI agent.
	ParticipantTypeBot ParticipantType = "Bot"
)

type ResponseError 

type ResponseError struct {
	StatusCode int
	Message    string
	Details    map[string]any
}

ResponseError represents an error response from the API.

func (*ResponseError) Error 

func (re *ResponseError) Error() string

Error satisfies the error interface.

func (*ResponseError) TraceID 

func (re *ResponseError) TraceID() string

TraceID returns the identifier that can be given to Gradient Labs technical support to investigate an error.

type StartConversationParams 

type StartConversationParams struct {
	// ID uniquely identifies the conversation.
	//
	// Can be anything consisting of letters, numbers, or any of the following
	// characters: _ - + =.
	//
	// Tip: use something meaningful to your business (e.g. a ticket number).
	ID string `json:"id"`

	// CustomerID uniquely identifies the customer. Used to build historical
	// context of conversations the agent has had with this customer.
	CustomerID string `json:"customer_id"`

	// Channel represents the way a customer is getting in touch. It will be used
	// to determine how the agent formats responses, etc.
	Channel Channel `json:"channel"`

	// Metadata is arbitrary metadata that will be attached to the conversation.
	// It will be passed along with webhooks so can be used as action parameters.
	Metadata any `json:"metadata"`
}

StartConversationParams are the parameters to Client.StartConversation.

type Status 

type Status string

Status describes the current state of the conversation. 

const (
	// StatusObserving indicates the agent is following the conversation but not
	// participating (e.g. when it has been handed-off to a human).
	StatusObserving Status = "observing"

	// StatusActive indicates the agent is actively participating in the
	// conversation.
	StatusActive Status = "active"

	// StatusCancelled indicates the conversation has been prematurely brought to
	// a close (e.g. because a human has taken it over) and the AI agent can no
	// longer participate in it.
	StatusCancelled Status = "cancelled"

	// StatusFinished indicates the conversation has been closed because the
	// customer's issue has been resolved.
	StatusFinished Status = "finished"

	// StatusFailed indicates the agent encountered an irrecoverable error, such as
	// not being able to deliver a message to your webhook endpoint after multiple
	// retries.
	StatusFailed Status = "failed"
)

type Webhook 

type Webhook struct {
	// ID uniquely identifies this event.
	ID string `json:"id"`

	// Type indicates the type of event.
	Type WebhookType `json:"type"`

	// SequenceNumber can be used to establish an order of webhook events.
	// For more information, see: https://api-docs.gradient-labs.ai/#sequence-numbers
	SequenceNumber int `json:"sequence_number"`

	// Timestamp is the time at which this event was generated.
	Timestamp time.Time `json:"timestamp"`

	// Data contains the event data. Use the helper methods (e.g.
	// Webhook.AgentMessage) to access it.
	Data any `json:"-"`
}

Webhook is an event delivered to your webhook endpoint.

func (Webhook) AgentMessage 

func (w Webhook) AgentMessage() (*AgentMessageEvent, bool)

AgentMessage returns the data for an `agent.message` event.

func (Webhook) ConversationFinished 

func (w Webhook) ConversationFinished() (*ConversationFinishedEvent, bool)

ConversationFinished returns the data for an `conversation.finished` event.

func (Webhook) ConversationHandOff 

func (w Webhook) ConversationHandOff() (*ConversationHandOffEvent, bool)

ConversationHandOff returns the data for an `conversation.hand_off` event.

type WebhookConversation 

type WebhookConversation struct {
	// ID is chosen unique identifier for this conversation.
	ID string `json:"id"`

	// CustomerID is your chosen identifier for the customer.
	CustomerID string `json:"customer_id"`

	// Metadata you attached to the conversation with Client.StartConversation.
	Metadata any `json:"metadata"`
}

WebhookConversation contains the details of the conversation the webhook relates to.

type WebhookType 

type WebhookType string

WebhookType indicates the type of webhook event. 

const (
	// WebhookTypeAgentMessage indicates the agent wants to send the customer a
	// message.
	WebhookTypeAgentMessage WebhookType = "agent.message"

	// WebhookTypeConversationHandOff indicates the agent is escalating or handing
	// the conversation off to a human agent.
	WebhookTypeConversationHandOff WebhookType = "conversation.hand_off"

	// WebhookTypeConversationFinished indicates the agent has concluded the
	// conversation with the customer and you should close any corresponding
	// ticket, etc.
	WebhookTypeConversationFinished WebhookType = "conversation.finished"
)

type WebhookVerifier 

type WebhookVerifier struct {
	// contains filtered or unexported fields
}

WebhookVerifier verifies the authenticity of requests to your webhook endpoint using the X-GradientLabs-Signature header.

func (WebhookVerifier) VerifyRequest 

func (v WebhookVerifier) VerifyRequest(req *http.Request) error

VerifyRequest verifies the authenticity of the given request using its signature header.

func (WebhookVerifier) VerifySignature 

func (v WebhookVerifier) VerifySignature(body []byte, sig string) error

VerifySignature is a lower level variant of VerifyRequest

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.