client

package module
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Aug 1, 2025 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

View Source 
const CacheNever = "never"

CacheNever means the pull resource will be refreshed on every turn of the conversation.

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 ActionExecuteEvent added in v0.2.1 

type ActionExecuteEvent struct {
	// Action is the name of the action to execute
	Action string `json:"action"`

	// Params are the arguments to execute the action with.
	Params json.RawMessage `json:"params"`

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

ActionExecuteEvent contains the data for a `action.execute` event.

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.
	// This cannot be set to ParticipantTypeAI.
	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"`

	// Attachments contains any files that were uploaded with this message.
	Attachments []*Attachment `json:"attachments,omitempty"`
}

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"`

	// Total identifies the number of agent messages that have been
	// produced in the current turn.
	Total int `json:"total,omitempty"`

	// Sequence identifies which agent message this is in the current turn.
	Sequence int `json:"sequence,omitempty"`

	// Intent is the most recent intent that was classified from the customer's
	// conversation, if any.
	Intent string `json:"intent,omitempty"`
}

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

type AgentMetadata added in v0.3.2 

type AgentMetadata struct {
	// Intent is the name of the *latest* intent that the agent has
	// classified for this conversation.
	Intent string `json:"intent,omitempty"`

	// IntentHandOffTarget is the ID of the hand off target that
	// is currently associated with the latest intent.
	IntentHandOffTarget string `json:"intent_handoff_target,omitempty"`

	// HandOffReason is the coded reason why the agent has handed off
	// the conversation (if at all).
	HandOffReason string `json:"handoff_reason,omitempty"`

	// HandOffNote is the free-text note that the agent generated
	// to summarize what it has done so far when handing off the
	// conversation.
	HandOffNote string `json:"handoff_note,omitempty"`
}

type Argument added in v0.3.2 

type Argument struct {
	// Name is the parameter name.
	Name string `json:"name"`

	// Value is the value of the argument.
	// It is a string here, but it will be converted to the
	// appropriate type when the tool is called.
	Value string `json:"value"`
}

type AssignmentParams added in v0.1.3 

type AssignmentParams struct {
	// AssigneeID optionally identifies the specific user that the conversation
	// is being assigned to.
	AssigneeID string `json:"assignee_id,omitempty"`

	// AssigneeType identifies the type of participant that this conversation is
	// being assigned to. Set this to ParticipantTypeAIAgent to assign the conversation
	// to the Gradient Labs AI agent.
	AssigneeType ParticipantType `json:"assignee_type"`

	// Timestamp optionally defines the time when the conversation was assigned.
	// If not given, this will default to the current time.
	Timestamp *time.Time `json:"timestamp,omitempty"`

	// Reason optionally allows you to describe why this assignment is happening.
	Reason string `json:"reason,omitempty"`
}

type AsyncDefinition added in v0.3.5 

type AsyncDefinition struct {
	// StartExecutionTool is the tool that will be executed to start the async operation. It should return a result
	// fairly quickly that optionally contains information about the work that has been kicked off. It is executed like
	// a normal HTTP/Webhook tool.
	StartExecutionTool ChildTool `json:"start_execution_tool"`

	// Timeout is the maximum time the async operation is allowed to run. If it exceeds this time, we will stop waiting
	// for the response and the agent will be notified that the async operation has timed out.
	Timeout time.Duration `json:"timeout"`
}

type Attachment added in v0.1.1 

type Attachment struct {
	// Type of file that was uploaded.
	Type AttachmentType `json:"type"`

	// FileName is the name of the file that was uploaded.
	FileName string `json:"file_name"`
}

Attachment represents a file that was uploaded with a message.

type AttachmentType added in v0.1.1 

type AttachmentType string

AttachmentType identifies the type of file that has been attached to a message. Currently, our AI agent does not support processing attachments, and will hand the conversation off to a human agent if it encounters one. 

const (
	// AttachmentTypeImage indicates that the attachment is an image.
	AttachmentTypeImage AttachmentType = "image"

	// AttachmentTypeFile indicates that the attachment is a generic file such as
	// a document.
	AttachmentTypeFile AttachmentType = "file"
)

type Attribute added in v0.3.4 

type Attribute struct {
	// Path expression to read this attribute from a resource payload.
	Path string `json:"path"`

	// Type describes the data type of the attribute.
	Type AttributeType `json:"type"`

	// Cardinality determines how many values would be returned when applying the
	// given JSONPath. Only attributes with a cardinality of "one" can be used as
	// tool parameter values.
	Cardinality AttributeCardinality `json:"cardinality"`

	// Description is an optional human-readable description of the attribute.
	Description string `json:"description"`

	// IsTopLevel is true if the attribute is a top-level field (direct child of the root).
	IsTopLevel bool `json:"is_top_level"`

	// Name is the name of the field, e.g.:
	//   - "id" for `$.id`
	//   - "quantity" for `$.items[*].quantity`
	Name string `json:"name"`
}

type AttributeCardinality added in v0.3.4 

type AttributeCardinality string

AttributeCardinality determines how many values would be returned when applying an attribute's JSONPath to a resource payload. 

const (
	// AttributeCardinalityOne means the attribute represents one value (e.g.
	// `$.id` or `$.name`).
	AttributeCardinalityOne AttributeCardinality = "one"

	// AttributeCardinalityMany means the attribute represents many values (e.g.
	// `$.items[*].quantity`).
	AttributeCardinalityMany AttributeCardinality = "many"
)

type AttributeType added in v0.3.4 

type AttributeType string

AttributeType describes the data type of the attribute. 

const (
	// AttributeTypeString means the attribute is a string.
	AttributeTypeString AttributeType = "string"

	// AttributeTypeDate means the attribute is a date in the string form:
	// YYYY-MM-DD.
	AttributeTypeDate AttributeType = "date"

	// AttributeTypeTimestamp means the attribute is a timestamp in the RFC3339 form.
	AttributeTypeTimestamp AttributeType = "timestamp"

	// AttributeTypeBoolean means the attribute is a boolean value.
	AttributeTypeBoolean AttributeType = "boolean"

	// AttributeTypeNumber means the attribute is a numeric value. JSON doesn't
	// differentiate between integers and floating point numbers, so it's up to
	// the user to interpret this.
	AttributeTypeNumber AttributeType = "number"

	// AttributeTypeArray means the attribute is an array of primitive values.
	//
	// Note: an array of primitive values will still have a cardinality of "one"
	// because there is one value available (the array itself).
	AttributeTypeArray AttributeType = "array"

	// AttributeTypeComplex means the attribute could be many types, which we don't
	// support yet.
	AttributeTypeComplex AttributeType = "complex"
)

type BodyEncoding added in v0.2.8 

type BodyEncoding string

BodyEncoding determines how the HTTP body will be encoded. 

const (
	// BodyEncodingForm indicates the body will be encoded using URL encoding.
	BodyEncodingForm BodyEncoding = "application/x-www-form-urlencoded"

	// BodyEncodingJSON indicates the body will be encoded as JSON.
	BodyEncodingJSON BodyEncoding = "application/json"
)

type CancelParams added in v0.2.1 

type CancelParams struct {
	// Timestamp optionally defines the time when the conversation was cancelled.
	// If not given, this will default to the current time.
	Timestamp *time.Time `json:"timestamp,omitempty"`

	// Reason optionally allows you to describe why this cancellation is happening.
	Reason string `json:"reason,omitempty"`
}

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 is deprecated. It indicates the customer is getting in
	// touch via a live instant message chat.
	ChannelWeb Channel = "web"

	// ChannelChat is used for live chat conversations.
	ChannelChat Channel = "web"

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

type ChildTool added in v0.3.5 

type ChildTool struct {
	Webhook *ToolWebhookConfiguration `json:"webhook,omitempty"`
	HTTP    *HTTPDefinition           `json:"http,omitempty"`
}

ChildTool represents a tool that is part of a parent tool's configuration. It does not have its own ID, company ID, version, dates, authors, etc. as these are all inherited from the parent tool. In its current form it effectively maps to an action definition.

Note that the child tool does not currently support parameters, these are decided by the parent tool and passed to the child tool when it is executed.

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) AddConversationEvent added in v0.1.5 

func (c *Client) AddConversationEvent(ctx context.Context, conversationID string, p *EventParams) error

AddConversationEvent records an event such as the customer started typing.

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) AddResource added in v0.1.6 

func (c *Client) AddResource(ctx context.Context, conversationID string, name string, resource any) error

AddResource adds (or updates) a resource to the conversation (e.g. the customer's order details) so the AI agent can handle customer-specific queries.

A resource can be any JSON document, as long it is smaller than 1MB. There are no strict requirements on the format/structure of the document, but we recommend making attribute names as descriptive as possible.

Over time, the AI agent will learn the structure of your resources - so while it's fine to add new attributes, you may want to consider using new resource names when removing attributes or changing the structure of your resources significantly.

Resource names are case-insensitive and can be anything consisting of letters, numbers, or any of the following characters: _ - + =.

Names should be descriptive handles that are the same for all conversations (e.g. "order-details" and "user-profile") not unique identifiers.

func (*Client) AssignConversation added in v0.1.3 

func (c *Client) AssignConversation(ctx context.Context, conversationID string, p *AssignmentParams) error

AssignConversation assigns a conversation to a participant.

func (*Client) CancelConversation 

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

CancelConversation cancels the conversation.

This is intended for cases where the conversation is being explicitly cancelled or terminated. Use FinishConversation() when the conversation is has reached a natural 'end' state, such as it being resolved or closed due to inactivity.

func (*Client) CreateResourceSource added in v0.3.4 

func (c *Client) CreateResourceSource(ctx context.Context, req *ResourceSourceCreateParams) (*ResourceSource, error)

CreateResourceSource creates a new resource source.

Note: requires a `Management` API key.

func (*Client) CreateResourceType added in v0.3.4 

func (c *Client) CreateResourceType(ctx context.Context, req *ResourceTypeCreateParams) (*ResourceType, error)

CreateResourceType creates a new resource type.

Note: requires a `Management` API key.

func (*Client) CreateTool added in v0.2.8 

func (c *Client) CreateTool(ctx context.Context, p *Tool) (*Tool, error)

CreateTool creates a new tool.

Note: requires a `Management` API key.

func (*Client) DeleteArticle added in v0.3.5 

func (c *Client) DeleteArticle(ctx context.Context, articleID string) error

DeleteArticle marks an article as deleted. Copies of the article are kept in case they are needed to render citations.

func (*Client) DeleteHandOffTarget added in v0.3.5 

func (c *Client) DeleteHandOffTarget(ctx context.Context, p *HandOffTargetDeleteParams) error

DeleteHandOffTarget deletes a hand-off target. This will fail if the hand off target is in use - either in a procedure, or in an intent.

Note: requires a `Management` API key.

func (*Client) DeleteResourceSource added in v0.3.4 

func (c *Client) DeleteResourceSource(ctx context.Context, id string) error

DeleteResourceSource deletes a resource source by its ID.

Note: requires a `Management` API key.

func (*Client) DeleteResourceType added in v0.3.4 

func (c *Client) DeleteResourceType(ctx context.Context, id string) error

DeleteResourceType deletes a resource type by its ID.

Note: requires a `Management` API key.

func (*Client) DeleteTool added in v0.3.2 

func (c *Client) DeleteTool(ctx context.Context, toolID string) error

DeleteTool deletes a tool. Note: You can't delete a tool that is currently in use in a live procedure.

Note: requires a `Management` API key.

func (*Client) ExecuteTool added in v0.3.2 

func (c *Client) ExecuteTool(ctx context.Context, p *ExecutionParams) (*ExecuteResult, error)

ExecuteTool executes a tool with the provided arguments, so that you can test a tool end-to-end.

Note: requires a `Management` API key.

func (*Client) FinishConversation added in v0.2.1 

func (c *Client) FinishConversation(ctx context.Context, conversationID string, p FinishParams) error

FinishConversation finishes a conversation.

A conversation finishes when it has come to its natural conclusion. This could be because the customer's query has been resolved, a human agent or other automation has closed the chat, or because the chat is being closed due to inactivity.

func (*Client) ListHandOffTargets added in v0.2.7 

func (c *Client) ListHandOffTargets(ctx context.Context) (*HandOffTargets, error)

ListHandOffTargets returns all of your hand off targets.

Note: requires a `Management` API key.

func (*Client) ListProcedureVersions added in v0.3.5 

func (c *Client) ListProcedureVersions(ctx context.Context, procedureID string) (*ListProcedureVersionsResponse, error)

func (*Client) ListProcedures added in v0.3.0 

func (c *Client) ListProcedures(ctx context.Context, p *ProcedureListParams) (*ProcedureListResponse, error)

ListProcedures lists procedures.

Note: requires a `Management` API key.

func (*Client) ListResourceSources added in v0.3.4 

func (c *Client) ListResourceSources(ctx context.Context) (*ResourceSourceListResponse, error)

ListResourceSources lists all resource sources accessible to the caller's company.

Note: requires a `Management` API key.

func (*Client) ListResourceTypes added in v0.3.4 

func (c *Client) ListResourceTypes(ctx context.Context) (*ResourceTypeListResponse, error)

ListResourceTypes lists all resource types accessible to the caller's company.

Note: requires a `Management` API key.

func (*Client) ListTools added in v0.2.9 

func (c *Client) ListTools(ctx context.Context) ([]*Tool, error)

ListTools retrieves all tools.

Note: requires a `Management` API key.

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) RateConversation added in v0.2.9 

func (c *Client) RateConversation(ctx context.Context, conversationID string, p *AssignmentParams) error

RateConversation submits a customer (CSAT) rating for a conversation.

func (*Client) ReadConversation added in v0.1.3 

func (c *Client) ReadConversation(ctx context.Context, conversationID string, p *ReadParams) (*Conversation, error)

func (*Client) ReadProcedure added in v0.3.0 

func (c *Client) ReadProcedure(ctx context.Context, procedureID string) (*Procedure, error)

ReadProcedure returns a procedure.

Note: requires a `Management` API key.

func (*Client) ReadResourceSource added in v0.3.4 

func (c *Client) ReadResourceSource(ctx context.Context, id string) (*ResourceSource, error)

ReadResourceSource retrieves a specific resource source by its ID.

Note: requires a `Management` API key.

func (*Client) ReadResourceType added in v0.3.4 

func (c *Client) ReadResourceType(ctx context.Context, id string) (*ResourceType, error)

ReadResourceType retrieves a specific resource type by its ID.

Note: requires a `Management` API key.

func (*Client) ReadTool added in v0.2.8 

func (c *Client) ReadTool(ctx context.Context, toolID string) (*Tool, error)

ReadTool retrieves a new tool.

Note: requires a `Management` API key.

func (*Client) SetArticleUsageStatus added in v0.3.5 

func (c *Client) SetArticleUsageStatus(ctx context.Context, articleID string, p *SetArticleUsageStatusParams) error

SetArticleUsageStatus updates an article's usage status. Use this to make it (un)available for use by the AI agent.

func (*Client) SetDefaultHandOffTarget added in v0.3.5 

func (c *Client) SetDefaultHandOffTarget(ctx context.Context, p *SetDefaultHandOffTargetParams) error

SetDefaultHandOffTarget sets the default hand off target that the AI agent will use when handing off the conversation, if there is no specific target for that intent or procedure.

Note: requires a `Management` API key.

func (*Client) SetProcedureExperimentVersion added in v0.3.5 

func (c *Client) SetProcedureExperimentVersion(ctx context.Context, procedureID string, version int, p *SetProcedureExperimentVersionParams) error

SetProcedureExperimentVersion sets the experiment version of procedure.

Note: requires a `Management` API key.

func (*Client) SetProcedureLimit added in v0.3.0 

func (c *Client) SetProcedureLimit(ctx context.Context, procedureID string, p *ProcedureLimitParams) (*Procedure, error)

SetProcedureLimit updates the daily usage limit of a procedure.

Note: requires a `Management` API key.

func (*Client) SetProcedureLiveVersion added in v0.3.5 

func (c *Client) SetProcedureLiveVersion(ctx context.Context, procedureID string, version int) error

SetProcedureLiveVersion sets the live version of procedure.

Note: requires a `Management` API key.

func (*Client) StartConversation 

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

StartConversation begins a conversation.

func (*Client) UnsetProcedureExperimentVersion added in v0.3.5 

func (c *Client) UnsetProcedureExperimentVersion(ctx context.Context, procedureID string, version int) error

UnsetProcedureExperimentVersion unsets the experiment version of procedure.

Note: requires a `Management` API key.

func (*Client) UnsetProcedureLiveVersion added in v0.3.5 

func (c *Client) UnsetProcedureLiveVersion(ctx context.Context, procedureID string, version int) error

UnsetProcedureLiveVersion unsets the live version of procedure.

Note: requires a `Management` API key.

func (*Client) UpdateResourceSource added in v0.3.4 

func (c *Client) UpdateResourceSource(ctx context.Context, id string, req *ResourceSourceUpdateParams) (*ResourceSource, error)

UpdateResourceSource updates an existing resource source.

Note: requires a `Management` API key.

func (*Client) UpdateResourceType added in v0.3.4 

func (c *Client) UpdateResourceType(ctx context.Context, id string, req *ResourceTypeUpdateParams) (*ResourceType, error)

UpdateResourceType updates an existing resource type.

Note: requires a `Management` API key.

func (*Client) UpdateTool added in v0.2.8 

func (c *Client) UpdateTool(ctx context.Context, p *UpdateToolParams) (*Tool, error)

UpdateTool updates an existing tool. It allows callers to convert mock tools into real tools, but not the other way around.

Note: requires a `Management` API key.

func (*Client) UpsertArticle added in v0.1.8 

func (c *Client) UpsertArticle(ctx context.Context, p *UpsertArticleParams) error

UpsertArticle inserts or updates a help article

func (*Client) UpsertArticleTopic added in v0.1.8 

func (c *Client) UpsertArticleTopic(ctx context.Context, p *UpsertArticleTopicParams) error

func (*Client) UpsertHandOffTarget added in v0.2.0 

func (c *Client) UpsertHandOffTarget(ctx context.Context, p *UpsertHandOffTargetParams) error

UpsertHandOffTarget inserts or updates a hand-off target.

Note: requires a `Management` API key.

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"`

	// IsActive is true if the AI agent is currently assigned to response
	// in this conversation.
	IsActive bool `json:"agent_is_active"`

	// AgentMetadata contains several fields that come from the agent.
	AgentMetadata *AgentMetadata `json:"latest_agent_metadata,omitempty"`
}

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

type ConversationEventType added in v0.1.5 

type ConversationEventType string

ConversationEventType describes an event that occurred within the conversation. 

const (
	// ConversationEventInternalNote means that a human agent (or bot) has added
	// a message into the conversation that is not visible to the customer.
	ConversationEventInternalNote ConversationEventType = "internal-note"

	// ConversationEventTypeJoin means the customer or human agent joined the
	// conversation.
	ConversationEventTypeJoin ConversationEventType = "join"

	// ConversationEventTypeLeave means the customer or human agent left the
	// conversation.
	ConversationEventTypeLeave ConversationEventType = "leave"

	// ConversationEventTypeMessageDelivered means that a message has been delivered
	// to a participant
	ConversationEventTypeMessageDelivered ConversationEventType = "delivered"

	// ConversationEventTypeMessageDelivered means that a message has been read
	// by the participant it was delivered to
	ConversationEventTypeMessageRead ConversationEventType = "read"

	// ConversationEventTypeTyping means the customer or human agent started typing.
	ConversationEventTypeTyping ConversationEventType = "typing"
)

type ConversationFinishedEvent 

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

	// Reason is the code that describes why the agent wants to finish this
	// conversation.
	Reason string `json:"reason_code,omitempty"`

	// Intent is the most recent intent that was classified from the customer's
	// conversation, if any.
	Intent string `json:"intent,omitempty"`
}

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"`

	// Target defines where the agent wants to hand this conversation to.
	Target string `json:"target,omitempty"`

	// Reason is the code that describes why the agent wants to hand off this
	// conversation.
	Reason string `json:"reason_code"`

	// Description is a human-legible description of the Reason code.
	Description string `json:"reason"`

	// Intent is the most recent intent that was classified from the customer's
	// conversation, if any.
	Intent string `json:"intent,omitempty"`
}

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

type EventParams added in v0.1.5 

type EventParams struct {
	// Type identifies the type of event (see: ConversationEventType).
	Type ConversationEventType `json:"type"`

	// 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"`

	// MessageID optionally identifies the message that this event relates to
	MessageID *string `json:"message_id,omitempty"`

	// Timestamp optionally defines the time when the conversation was assigned.
	// If not given, this will default to the current time.
	Timestamp *time.Time `json:"timestamp,omitempty"`

	// IdempotencyKey optionally enables you to safely retry requests
	IdempotencyKey string `json:"idempotency_key,omitempty"`
}

type ExecuteResult added in v0.3.2 

type ExecuteResult struct {
	ID string `json:"id"`

	// Result is the JSON-encoded result of the tool execution.
	RawResult json.RawMessage `json:"raw"`
}

type ExecutionParams added in v0.3.2 

type ExecutionParams struct {
	ID string `json:"id"`

	Arguments []Argument `json:"arguments"`
}

type ExperimentalConfig added in v0.3.5 

type ExperimentalConfig struct {
	MaxDailyConversations int
}

type FinishParams added in v0.2.1 

type FinishParams struct {
	// Timestamp optionally defines the time when the conversation ended.
	// If not given, this will default to the current time.
	Timestamp *time.Time `json:"timestamp,omitempty"`

	// Reason optionally allows you to describe why this conversation is finishing.
	Reason string `json:"reason,omitempty"`
}

type HTTPBodyDefinition added in v0.3.2 

type HTTPBodyDefinition struct {
	Encoding           BodyEncoding      `json:"encoding"`
	JSONTemplate       string            `json:"json_template,omitempty"`
	FormFieldTemplates map[string]string `json:"form_field_templates,omitempty"`
}

type HTTPDefinition added in v0.3.2 

type HTTPDefinition struct {
	Method          string              `json:"method"`
	URLTemplate     string              `json:"url_template"`
	HeaderTemplates map[string]string   `json:"header_templates,omitempty"`
	Body            *HTTPBodyDefinition `json:"body,omitempty"`
}

type HandOffTarget added in v0.2.7 

type HandOffTarget struct {
	// ID is your identifier of choice for this hand-off target. Can be anything consisting
	// of letters, numbers, or any of the following characters: `_` `-` `+` `=`.
	ID string `json:"id"`

	// Name is the hand-off target’s name.
	Name string `json:"name"`
}

type HandOffTargetDeleteParams added in v0.3.5 

type HandOffTargetDeleteParams struct {
	// ID is the unique identifier for the hand-off target to delete
	ID string `json:"id"`
}

type HandOffTargets added in v0.2.7 

type HandOffTargets struct {
	Targets []*HandOffTarget `json:"targets"`
}

type ListProcedureVersionsResponse added in v0.3.5 

type ListProcedureVersionsResponse struct {
	Versions []*ProcedureVersion `json:"versions"`
}

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"`

	// Attachments contains any files that were uploaded with this message.
	Attachment []*Attachment `json:"attachments,omitempty"`
}

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 PaginationInfo added in v0.3.0 

type PaginationInfo struct {
	// Next is a cursor to retrieve the next page of results.
	Next *string `json:"next,omitempty"`

	// Prev is a cursor to retrieve the previous page of results.
	Prev *string `json:"prev,omitempty"`
}

type ParameterOption added in v0.2.9 

type ParameterOption struct {
	Value string `json:"value"`
	Text  string `json:"text"`
}

type ParameterType added in v0.2.8 

type ParameterType string

ParameterType determines the data type of a parameter. 

const (
	// ParameterTypeString indicates the parameter accepts string/text values.
	ParameterTypeString ParameterType = "string"
)

type ParticipantType 

type ParticipantType string

ParticipantType identifies the type of participant who sent a message or is assigned to a conversation. 

const (
	// ParticipantTypeCustomer is a  customer/end-user.
	ParticipantTypeCustomer ParticipantType = "Customer"

	// ParticipantTypeHumanAgent is a human support agent.
	ParticipantTypeHumanAgent ParticipantType = "Agent"

	// ParticipantTypeBot is an automation/bot other than the Gradient Labs AI agent.
	ParticipantTypeBot ParticipantType = "Bot"

	// ParticipantTypeAIAgent is the Gradient Labs AI agent.
	ParticipantTypeAIAgent ParticipantType = "AI Agent"
)

type Procedure added in v0.3.0 

type Procedure struct {
	// ID uniquely identifies the procedure.
	ID string `json:"id"`

	// Name is the user-given name of the procedure.
	Name string `json:"name"`

	// Description is the user-given description for the procedure
	Description string `json:"description"`

	// Status is the overall status of the procedure.
	Status ProcedureStatus `json:"status"`

	// Author is the user who originally created the procedure.
	Author *UserDetails `json:"author"`

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

	// Updated is the time at which the procedure's status, metadata, or current
	// revision was last changed. It does *not* reflect revisions created as part
	// of testing unsaved changes.
	Updated time.Time `json:"updated"`

	// IsDailyLimited is true if this procedure can only be executed for a maximum
	// number of conversations in a given day (defined below).
	IsDailyLimited bool `json:"has_daily_limit"`

	// MaxDailyConversations is the maximum number of conversations that a procedure
	// can be used in on a given day, when it is rate limited.
	MaxDailyConversations int `json:"max_daily_conversations,omitempty"`
}

type ProcedureLimitParams added in v0.3.0 

type ProcedureLimitParams struct {
	// HasDailyLimit identifies whether the procedure should have a limit
	HasDailyLimit bool `json:"has_daily_limit,omitempty"`

	// MaxDailyConversations is the maximum number of conversations that
	// can use this procedure on a given day.
	MaxDailyConversations int `json:"max_daily_conversations,omitempty"`
}

type ProcedureListParams added in v0.3.0 

type ProcedureListParams struct {
	// Cursor is used to retrieve the next/previous page of the list.
	Cursor string `json:"cursor,omitempty"`

	// Status is used to filter the list of procedures by status.
	Status ProcedureStatus `json:"status,omitempty"`
}

type ProcedureListResponse added in v0.3.0 

type ProcedureListResponse struct {
	// Procedures contains the list of procedures.
	Procedures []*Procedure `json:"procedures"`

	// Pagination contains the pagination-related information.
	Pagination *PaginationInfo `json:"pagination"`
}

type ProcedureStatus added in v0.3.0 

type ProcedureStatus string
const (
	// ProcedureStatusDraft indicates the procedure has been saved as a draft, but
	// won't be used in real conversations until it is promoted to live.
	ProcedureStatusDraft ProcedureStatus = "draft"

	// ProcedureStatusLive indicates the procedure is live and will be used in real
	// conversations.
	ProcedureStatusLive ProcedureStatus = "live"
)

type ProcedureVersion added in v0.3.5 

type ProcedureVersion struct {
	// Name is the user-given name of the procedure at the time of this version.
	Name string
	// Description of the procedure at the time of this version.
	Description string
	// Version is a numeric identifier for the version. It is incremented every
	// time a new version of the procedure is saved.
	Version int
	// Author is the ID of the user who created this version of the procedure.
	Author string
	// Created is the time at which this version of the procedure was created.
	Created time.Time
	// Experimental indicates whether this is an experimental version that is used before "live",
	// within the daily limit defined in ExperimentalConfig.
	Experimental bool
	// ExperimentalConfig defines how the experimental version is limited. Relevant only if Experimental == true.
	ExperimentalConfig *ExperimentalConfig
	// Live indicates whether this is the "production" version that is used by the agent by default,
	// if there are no experimental versions or all of them have exceeded their limit.
	Live bool
}

type PublicationStatus added in v0.1.8 

type PublicationStatus string

PublicationStatus describes the status of a help article. 

const (
	// PublicationStatusDraft means that the article is being written or
	// edited and is not published.
	PublicationStatusDraft PublicationStatus = "draft"

	// PublicationStatusPublished means that the article is published.
	PublicationStatusPublished PublicationStatus = "published"
)

type RatingParams added in v0.2.9 

type RatingParams struct {

	// SurveyType identifies the type of survey sent to customers.
	SurveyType string `json:"type"`

	// Value is the rating value that was submitted by the customer.
	// It must be a value between [MinValue, MaxValue].
	Value int `json:"value"`

	// MaxValue is the maximum value in the rating scale.
	MaxValue int `json:"max_value"`

	// MinValue is the minimum value of the rating scale.
	MinValue int `json:"min_value"`

	// Comments optionally submits any free-text that was submitted by the
	// customer alongside their rating.
	Comments string `json:"comments,omitempty"`

	// Timestamp optionally defines the time when the conversation was rate.
	// If not given, this will default to the current time.
	Timestamp *time.Time `json:"timestamp,omitempty"`
}

type ReadParams added in v0.3.2 

type ReadParams struct {
	// SupportPlatform is the name of the support platform where the
	// conversation was started (e.g. Intercom).
	//
	// Leave empty if the conversation was started via the Gradient
	// Labs API.
	SupportPlatform string `json:"support_platform,omitempty"`
}

type RefreshStrategy added in v0.3.4 

type RefreshStrategy string
const (
	// RefreshStrategyDynamic means the resource value can change, so this is re-fetched throughout the conversation.
	RefreshStrategyDynamic RefreshStrategy = "dynamic"

	// RefreshStrategyStatic means the resource is fetched once at the start of the conversation (global) or when it's first used in a procedure (local).
	RefreshStrategyStatic RefreshStrategy = "static"
)

type ResourceHTTPBodyDefinition added in v0.3.4 

type ResourceHTTPBodyDefinition struct {
	// Encoding determines how the HTTP request body will be encoded.
	Encoding string `json:"encoding"`

	// JSONTemplate contains a template that will be used to generate JSON for the
	// HTTP request body. Only used when Encoding is "application/json".
	JSONTemplate string `json:"json_template,omitempty"`

	// FormFieldTemplates contains templates for the values that will be form-encoded
	// and used as the HTTP body. Only used when Encoding is "application/x-www-form-urlencoded".
	FormFieldTemplates map[string]string `json:"form_field_templates,omitempty"`
}

ResourceHTTPBodyDefinition determines how the HTTP request body is constructed.

type ResourceHTTPDefinition added in v0.3.4 

type ResourceHTTPDefinition struct {
	// Method is the HTTP request method that will be used.
	Method string `json:"method"`

	// URLTemplate contains a template used to construct the request URL.
	URLTemplate string `json:"url_template"`

	// Body determines how the HTTP request body is constructed.
	Body *HTTPBodyDefinition `json:"body,omitempty"`

	// HeaderTemplates contains templates for the values that will be used as request headers.
	HeaderTemplates map[string]string `json:"header_templates,omitempty"`
}

ResourceHTTPDefinition contains configuration for HTTP actions.

type ResourcePullEvent added in v0.2.5 

type ResourcePullEvent struct {
	// ResourceType is the name of the resource type the agent wants to pull.
	ResourceType string `json:"resource_type"`

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

ResourcePullEvent contains the data for a `resource.pull` event.

type ResourceSource added in v0.3.4 

type ResourceSource struct {
	// ID is a generated ID for the resource source.
	ID string `json:"id"`

	// DisplayName free-text field to describe the source, eg. "Intercom User Attributes". Enforced unique per
	// company.
	DisplayName string `json:"display_name"`

	// Description optional free-text field to describe the source in more detail. Not used by the agent at all, only
	// humans.
	Description string `json:"description"`

	// SourceType describes how the data is fetched from the source.
	SourceType SourceType `json:"source_type"`

	// HTTPConfig can be set up by customers.
	HTTPConfig *ResourceHTTPDefinition `json:"http_config,omitempty"`

	// WebhookConfig can be set up by customers.
	WebhookConfig *ResourceWebhookDefinition `json:"webhook_config,omitempty"`

	// AttributeDescriptions optional raw attribute-level descriptions, used when generating the schema and as
	// additional information for the agent.
	// - key: a JSONPath eg. `$.name` or `$.items[*].name`
	// - value: a description of the attribute
	AttributeDescriptions map[string]string `json:"attribute_descriptions,omitempty"`

	// Schema is the schema of the resource source, inferred from the source payloads. It is updated
	// asynchronously as data is fetched from the source. Nil if the schema has not been inferred yet. Includes
	// attribute descriptions if present.
	Schema *Schema `json:"schema,omitempty"`

	Created time.Time `json:"created"`
	Updated time.Time `json:"updated"`
}

ResourceSource represents a resource source in the system.

type ResourceSourceCreateParams added in v0.3.4 

type ResourceSourceCreateParams struct {
	DisplayName           string                     `json:"display_name"`
	Description           string                     `json:"description,omitempty"`
	SourceType            SourceType                 `json:"source_type"`
	HTTPConfig            *ResourceHTTPDefinition    `json:"http_config,omitempty"`
	WebhookConfig         *ResourceWebhookDefinition `json:"webhook_config,omitempty"`
	AttributeDescriptions map[string]string          `json:"attribute_descriptions,omitempty"`
}

ResourceSourceCreateParams represents the request to create a new resource source.

type ResourceSourceListResponse added in v0.3.4 

type ResourceSourceListResponse struct {
	ResourceSources []*ResourceSource `json:"resource_sources"`
}

ResourceSourceListResponse represents the response from listing resource sources.

type ResourceSourceUpdateParams added in v0.3.4 

type ResourceSourceUpdateParams struct {
	DisplayName           *string                    `json:"display_name,omitempty"`
	Description           *string                    `json:"description,omitempty"`
	SourceType            *SourceType                `json:"source_type,omitempty"`
	HTTPConfig            *ResourceHTTPDefinition    `json:"http_config,omitempty"`
	WebhookConfig         *ResourceWebhookDefinition `json:"webhook_config,omitempty"`
	AttributeDescriptions map[string]string          `json:"attribute_descriptions,omitempty"`
}

ResourceSourceUpdateParams represents the request to update an existing resource source.

type ResourceType added in v0.3.4 

type ResourceType struct {
	// ID is a generated ID for the resource type.
	ID string `json:"id"`

	// DisplayName is a freetext human-readable name for the resource type.
	DisplayName string `json:"display_name"`

	// Description is an optional freetext human-readable description of the resource type.
	Description string `json:"description"`

	// Scope determines when in the conversation the resource is fetched and used.
	Scope Scope `json:"scope"`

	// RefreshStrategy determines how often the resource is re-fetched.
	RefreshStrategy RefreshStrategy `json:"refresh_strategy"`

	// SourceConfig defines how the resource is fetched. If not set, the type can still be used in testing environments
	// with mocked data.
	SourceConfig *SourceConfig `json:"source_config,omitempty"`

	// Schema is the JSON schema for the resource type, optionally including attribute descriptions from the source if
	// IncludeDescriptions is true on read.
	Schema *Schema `json:"schema,omitempty"`

	// IsEnabled indicates whether the resource type has been configured as enabled or not.
	IsEnabled bool `json:"is_enabled"`

	Created time.Time `json:"created"`
	Updated time.Time `json:"updated"`
}

type ResourceTypeCreateParams added in v0.3.4 

type ResourceTypeCreateParams struct {
	DisplayName     string          `json:"display_name"`
	Description     string          `json:"description,omitempty"`
	Scope           Scope           `json:"scope"`
	RefreshStrategy RefreshStrategy `json:"refresh_strategy"`
	SourceConfig    *SourceConfig   `json:"source_config,omitempty"`
	IsEnabled       bool            `json:"is_enabled,omitempty"`
}

ResourceTypeCreateParams represents the request to create a new resource type.

type ResourceTypeListResponse added in v0.3.4 

type ResourceTypeListResponse struct {
	ResourceTypes []*ResourceType `json:"resource_types"`
}

ResourceTypeListResponse represents the response from listing resource types.

type ResourceTypeUpdateParams added in v0.3.4 

type ResourceTypeUpdateParams struct {
	DisplayName     *string          `json:"display_name,omitempty"`
	Description     *string          `json:"description,omitempty"`
	Scope           *Scope           `json:"scope,omitempty"`
	RefreshStrategy *RefreshStrategy `json:"refresh_strategy,omitempty"`
	SourceConfig    *SourceConfig    `json:"source_config,omitempty"`
	IsEnabled       *bool            `json:"is_enabled,omitempty"`
}

ResourceTypeUpdateParams represents the request to update an existing resource type.

type ResourceWebhookDefinition added in v0.3.4 

type ResourceWebhookDefinition struct {
	// Name will be included in the `data.action` field of the webhook payload.
	Name string `json:"name"`
}

ResourceWebhookDefinition contains configuration for webhook actions.

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 Schema added in v0.3.4 

type Schema struct {
	// Raw is the raw schema data.
	// - inferred from the data payloads
	// - updated asynchronously as data is fetched
	// - can be unmarshalled into a jsonschema.Schema (use Parse method)
	Raw json.RawMessage `json:"raw"`

	// Attributes is a list of attributes derived from the schema. Only leaf properties are included in this list,
	// container objects and arrays themselves are not included as separate attributes.
	//
	// For example, given a schema with:
	//   {
	//     "properties": {
	//       "name": { "type": "string" },
	//       "address": {
	//         "type": "object",
	//         "properties": {
	//           "street": { "type": "string" },
	//           "city": { "type": "string" }
	//         }
	//       },
	//       "skills": {
	//         "type": "array",
	//         "items": {
	//           "type": "object",
	//           "properties": {
	//             "name": { "type": "string" },
	//             "level": { "type": "string" }
	//           }
	//         }
	//       }
	//     }
	//   }
	//
	// The resulting attributes would be:
	//   - $.name (string)
	//   - $.address.street (string)
	//   - $.address.city (string)
	//   - $.skills[*].name (string)
	//   - $.skills[*].level (string)
	//
	// Note that $.address and $.skills are not included as separate attributes.
	// Attributes are sorted alphabetically by JSONPath.
	Attributes []Attribute `json:"attributes"`
}

Schema of data related to a resource.

type Scope added in v0.3.4 

type Scope string
const (
	// ScopeGlobal means the resource is available throughout the conversation and in all procedures.
	ScopeGlobal Scope = "global"

	// ScopeLocal means the resource is available only in procedures that explicitly use it, only fetched when it's used.
	ScopeLocal Scope = "local"
)

type SetArticleUsageStatusParams added in v0.3.5 

type SetArticleUsageStatusParams struct {
	UsageStatus UsageStatus `json:"usage_status"`
}

type SetDefaultHandOffTargetParams added in v0.3.5 

type SetDefaultHandOffTargetParams struct {
	// ID is the unique identifier for the hand-off target to set as default.
	// This should match an existing hand-off target's ID.
	// Set to empty string to clear the default.
	ID string `json:"id"`

	// Channel is the conversation channel for which to set the default hand-off target.
	Channel Channel `json:"channel"`
}

type SetProcedureExperimentVersionParams added in v0.3.5 

type SetProcedureExperimentVersionParams struct {
	// MaxDailyConversations limits how many conversations per day can use this version.
	// Allows gradual rollout of a new procedure version.
	MaxDailyConversations int `json:"max_daily_conversations"`

	// If Replace is true, an existing experiment (if any) will be replaced with a new one.
	// Otherwise, if another experiment already exists, an error will be returned.
	Replace bool `json:"replace"`
}

type SourceConfig added in v0.3.4 

type SourceConfig struct {
	// SourceID identifies the source which should be used to fetch the resource data.
	SourceID string `json:"source_id"`

	// Attributes defines the *top-level* fields names to be used from the source data. Eg. for a payload like this:
	//
	// “`
	// {
	//   "id": 123,
	//   "name": "foo",
	//   "items": [
	//     {
	//       "id": 1,
	//       "name": "bar"
	//     },
	//     {
	//       "id": 2,
	//       "name": "baz"
	//     }
	//   ],
	//	"nested": {
	//     "id": 456,
	//     "name": "qux"
	//   }
	// }
	// “`
	//
	// The following attributes would be valid:
	//   - "id"
	//   - "name"
	//   - "items"
	//   - "nested"
	// The following attributes would be invalid:
	//   - "items[*].id"
	//   - "nested.id"
	Attributes []string `json:"attributes"`

	// Cache determines how long we'll consider data from the source be valid before refreshing it. It's either a
	// duration string (e.g. "5m") or CacheNever if the resource is refreshed on every turn. The default is 1 minute.
	Cache string `json:"cache"`
}

type SourceType added in v0.3.4 

type SourceType string
const (
	SourceTypeHTTP     SourceType = "http"
	SourceTypeInternal SourceType = "internal"
	SourceTypeWebhook  SourceType = "webhook"
)

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"`

	// AssigneeID optionally identifies who the conversation is assigned to.
	AssigneeID string `json:"assignee_id,omitempty"`

	// AssigneeType optionally identifies which type of participant is currently
	// assigned to respond. Set this to ParticipantTypeAIAgent to assign the conversation
	// to the Gradient Labs AI when starting it.
	AssigneeType ParticipantType `json:"assignee_type,omitempty"`

	// 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 optionally defines the time when the conversation started.
	// If not given, this will default to the current time.
	Created *time.Time `json:"created,omitempty"`

	// Resources is an arbitrary object attached to the conversation and available to the AI agent
	// during the conversation. You can also use resources as parameters for your tools.
	Resources map[string]any `json:"resources,omitempty"`
}

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 Tool added in v0.2.8 

type Tool struct {
	ID          string                    `json:"id"`
	Name        string                    `json:"name"`
	Description string                    `json:"description"`
	Parameters  []ToolParameter           `json:"parameters"`
	Webhook     *ToolWebhookConfiguration `json:"webhook,omitempty"`
	HTTP        *HTTPDefinition           `json:"http,omitempty"`
	Async       *AsyncDefinition          `json:"async,omitempty"`
	Mock        bool                      `json:"mock,omitempty"`
}

type ToolList added in v0.2.9 

type ToolList struct {
	Tools []*Tool `json:"tools"`
}

type ToolParameter added in v0.2.8 

type ToolParameter struct {
	Name        string            `json:"name"`
	Description string            `json:"description"`
	Type        ParameterType     `json:"type"`
	Required    *bool             `json:"required,omitempty"`
	Options     []ParameterOption `json:"options,omitempty"`
}

type ToolWebhookConfiguration added in v0.2.8 

type ToolWebhookConfiguration struct {
	Name string `json:"name"`
}

type UpdateToolParams added in v0.3.2 

type UpdateToolParams struct {
	ID          string                    `json:"id"`
	Description string                    `json:"description"`
	Parameters  []ToolParameter           `json:"parameters"`
	Webhook     *ToolWebhookConfiguration `json:"webhook,omitempty"`
	HTTP        *HTTPDefinition           `json:"http,omitempty"`
	Mock        bool                      `json:"mock,omitempty"`
}

type UpsertArticleParams added in v0.1.8 

type UpsertArticleParams struct {
	// AuthorID optionally identifies the user who last edited the article
	AuthorID string `json:"author_id"`

	// ID is your identifier of choice for this article.
	ID string `json:"id"`

	// Title is the article's title. It may be empty if the article is a draft.
	Title string `json:"title"`

	// Description is an article's tagline. It may be empty.
	Description string `json:"description"`

	// Body is the main contents of an article. It may be empty if the article is a draft.
	Body string `json:"body"`

	// Visibility describes who can access this article, ranging from the
	// whole world (public) through to employees only (internal).
	Visibility Visibility `json:"visibility"`

	// TopicID optionally identifies the topic that this
	// article is associated with. If given, you must have created
	// the topic first (see: UpsertArticleTopic)
	TopicID string `json:"topic_id"`

	// PublicationStatus describes whether this article is published or not.
	PublicationStatus PublicationStatus `json:"status"`

	// Data optionally gives additional meta-data about the article.
	Data json.RawMessage `json:"data"`

	// Created is when the article was first authored.
	Created time.Time `json:"created"`

	// LastEdited is when the article was last changed.
	LastEdited time.Time `json:"last_edited"`
}

type UpsertArticleTopicParams added in v0.1.8 

type UpsertArticleTopicParams struct {
	// ID is your identifier for this topic
	ID string `json:"id"`

	// ParentID is the identifier for this topic's parent topic (if any).
	ParentID string `json:"parent_id"`

	// Name is the topic's name. This cannot be nil.
	Name string `json:"name"`

	// Description is an topic's tagline. It may be empty.
	Description string `json:"description"`

	// Visibility describes who can see this topic, ranging from the
	// whole world (public) through to employees only (internal).
	Visibility Visibility `json:"visibility"`

	// PublicationStatus describes whether this topic is published or not.
	PublicationStatus PublicationStatus `json:"status"`

	// Data optionally gives additional meta-data about the topic.
	Data json.RawMessage `json:"data"`

	// Created is when the topic was first created.
	Created time.Time `json:"created"`

	// LastEdited is when the topic was last changed.
	LastEdited time.Time `json:"last_edited"`
}

type UpsertHandOffTargetParams added in v0.2.0 

type UpsertHandOffTargetParams struct {
	// ID is your identifier of choice for this hand-off target. Can be anything consisting
	// of letters, numbers, or any of the following characters: `_` `-` `+` `=`.
	ID string `json:"id"`

	// Name is the hand-off target’s name. This cannot be nil.
	Name string `json:"name"`
}

type UsageStatus added in v0.3.5 

type UsageStatus string
const (
	UsageStatusOn  UsageStatus = "on"
	UsageStatusOff UsageStatus = "off"
)

type UserDetails added in v0.3.0 

type UserDetails struct {
	// Email identifies the user.
	Email string `json:"email"`
}

type Visibility added in v0.1.8 

type Visibility string

Visibility describes who can view the given item (e.g. help article) 

const (
	// VisibilityPublic means that the item is available to the general
	// public. For example, it is published on a public website.
	VisibilityPublic Visibility = "public"

	// VisibilityUsers means that the item is only available to the
	// company's customers. For example, it is only accessible via an
	// app after sign-up.
	VisibilityUsers Visibility = "users"

	// VisibilityInternal means that the item is only available to
	// the company's employees. For example, it is a procedure or SOP
	// that customers do not have access to.
	VisibilityInternal Visibility = "internal"
)

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) ActionExecute added in v0.2.1 

func (w Webhook) ActionExecute() (*ActionExecuteEvent, bool)

ActionExecute returns the data for an `action.execute` event.

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.

func (Webhook) ResourcePull added in v0.2.5 

func (w Webhook) ResourcePull() (*ResourcePullEvent, bool)

ResourcePull returns the data for an `resource.pull` 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"

	// WebhookTypeAction indicates that the agent needs an action to
	// be executed (e.g., while following a procedure)
	WebhookTypeActionExecute WebhookType = "action.execute"

	// WebhookTypeResourcePull indicates that the agent wants to pull a resource.
	WebhookTypeResourcePull WebhookType = "resource.pull"
)

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
examples
articles command
conversation command
handoff-targets command
procedure-versions command
procedures command

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.