wxas

README

Webex Assistant Skills - Go

This repository holds example skills and a cli utility written in Go for interacting with Webex Assistant Skills. For more information on Webex Assistant Skills, please see the official Webex Assistant Skills Overview.

It is intended as an alternative to the official Webex Assistant SDK, as documented in the Webex Assistant Skills Guide, without the need for installing python and the required dependencies. Simply download the binaries from the releases tab to get started.

It is currently a work in progress, so expect things to change as more is learned about this new webex feature.

Quick Start

You should be famililar with the Getting Started documentation. This quickstart assumes you'll be using the simulator to test.

Quick Start Requirements

To get started, you will need:

• Your tenant enabled for skills;

You will only need the following if you wish to register your skill from the CLI instead of using the Webex Assistant Skills Developer Portal:

• Your personal access token to register the skill: get your token here from the Copy button in the Authorization section;
• Your base64 decoded developer ID: get your ID and base64 decode it here taking the last part after ciscospark://us/PEOPLE/

You will only need the following if you wish to test your skill using the simulator:

• Your base64 decoded organisation ID (for the simulator): get your orgId and base64 decode it here taking the last part after ciscospark://us/ORGANIZATION/
• A token with the assistant scope to run the skill. You can temporarily get this from here until there is proper tooling;

Quick Start Steps

1. Create a folder and download the binaries from the releases page:
   a. wxa-cli - for generating the keys and the secret, along with registering your skill;
   b. echo-skill-secure - for the test skill;
   c. echo-skill-secure-tester for testing the skill locally;

2. Generate a public/private key pair:

$ ./wxa-cli generate-keys

1. Generate a secret:

$ ./wxa-cli generate-secret > secret.txt

1. (Optional) Set your environment variables or put them in a .env file:

SKILL_PUBLIC_KEY=<YOUR PUBLIC KEY HERE>
SKILL_PRIVATE_KEY=<YOUR PRIVATE KEY HERE>
SKILL_SECRET=<YOUR SECRET HERE>

If you don't set these, by default the skill will look in the current directory for secret.txt, private.pem and public.pem.

1. Set up a tunnel to your machine using localtunnel or ngrok, e.g:

ngrok http 8080

Use the https endpoint provided by ngrok in the next step.

1. Create the Skill on the Skills Service using the details obtained earlier:

You can do this on the Webex Assistant Skills Developer Portal as documented in the Webex Assistant Skills Guide Developer Portal Guide or use the wxa-cli command:

$ wxa-cli create-skill --name="Echo" --url="<YOUR_URL_FROM_STEP_5>" --contact="<YOUR_EMAIL>" -secret="$(cat secret.txt)" --public="$(cat public.pem)" --token="<YOUR_PERSONAL_ACCESS_TOKEN>" --developerid="<YOUR_DEVELOPER_ID>"

Replacing values in < > with the relevant details from earlier. Note the use of cat to provide the secret.txt and public.pem content into the command.

1. Run the skill:

$ ./echo-skill-secure

1. Test the skill locally:

$ ./echo-skill-secure-tester

1. Test the skill with the simulator:

• Visit https://assistant-web.intelligence.webex.com/.
• Enter the base64 decoded organisation ID and the assistant scoped token.
• Say or type ask echo hello there

Installation

Binaries

The simplest way is to download the binaries from the releases page.

Go Install

If you have Go installed, you can install using the following commands:

$ go install github.com/darrenparkinson/wxa-skills-go/cmd/wxa-cli@latest
$ go install github.com/darrenparkinson/wxa-skills-go/examples/echo-skill-secure@latest
$ go install github.com/darrenparkinson/wxa-skills-go/examples/echo-skill-secure/cmd/echo-skill-secure-tester@latest

Compiling from source

Again, if you have Go installed, you can also compile from source:

$ git clone https://github.com/darrenparkinson/wxa-skills-go
$ cd wxa-skills-go
$ go mod tidy
$ go build ./cmd/wxa-cli
$ go build ./examples/echo-skill-secure
$ go build ./examples/echo-skill-secure/echo-skill-secure-tester
$ ./wxa-cli --version

Documentation

Index

• Variables
• type Context
• type DirectiveName
  • func (n DirectiveName) MarshalJSON() ([]byte, error)
  • func (n DirectiveName) String() string
  • func (n *DirectiveName) UnmarshalJSON(data []byte) error
• type DirectiveType
  • func (t DirectiveType) MarshalJSON() ([]byte, error)
  • func (t DirectiveType) String() string
  • func (t *DirectiveType) UnmarshalJSON(data []byte) error
• type Frame
• type History
• type Params
• type Payload
• type WebexAssistantDirective
• type WebexAssistantHealthResponse
• type WebexAssistantMessage
• type WebexAssistantRequest
• type WebexAssistantResponse

Variables

var (
	// DirectiveNameReply provides the reply directive name
	DirectiveNameReply = DirectiveName{"reply"}
	// DirectiveNameLongReply provides the long-reply directive name
	DirectiveNameLongReply = DirectiveName{"long-reply"}
	// DirectiveNameSpeak provides the speak directive name
	DirectiveNameSpeak = DirectiveName{"speak"}
	// DirectiveNameListen provides the listen directive name
	DirectiveNameListen = DirectiveName{"listen"}
	// DirectiveNameSleep provides the sleep directive name
	DirectiveNameSleep = DirectiveName{"sleep"}
	// DirectiveNameUIHint provides the ui-hint directive name
	DirectiveNameUIHint = DirectiveName{"ui-hint"}
	// DirectiveNameASRHint provides the asr-hint directive name
	DirectiveNameASRHint = DirectiveName{"asr-hint"}
	// DirectiveNameDisplay provides the display directive name
	DirectiveNameDisplay = DirectiveName{"display"}
	// DirectiveNameDisplayWebView provides the display-web-view directive name
	DirectiveNameDisplayWebView = DirectiveName{"display-web-view"}
	// DirectiveNameClearWebView provides the clear-web-view directive name
	DirectiveNameClearWebView = DirectiveName{"clear-web-view"}
	// DirectiveNameAssistantEvent provides the assistant-event directive name
	DirectiveNameAssistantEvent = DirectiveName{"assistant-event"}
	// DirectiveTypeView provides the view directive name
	DirectiveTypeView = DirectiveType{"view"}
	// DirectiveTypeAction provides the action directive name
	DirectiveTypeAction = DirectiveType{"action"}
)

Types

type Context

type Context struct {
	OrgID               *string  `json:"orgId,omitempty"`               // The org id of the user making the request
	UserID              *string  `json:"userId,omitempty"`              // The id of the user making the request
	UserType            *string  `json:"userType,omitempty"`            // "user",  # The user type
	SupportedDirectives []string `json:"supportedDirectives,omitempty"` // The list of directives supported by the client making the request, e.g. sleep, listen, reply, speak
	DeveloperDeviceID   *string  `json:"developerDeviceId,omitempty"`
}

Context contains some information about how the user is making the request.

type DirectiveName

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

DirectiveName provides a strongly typed enum for directive names

func (DirectiveName) MarshalJSON

func (n DirectiveName) MarshalJSON() ([]byte, error)

MarshalJSON implements the Marshaler interface

func (DirectiveName) String

func (n DirectiveName) String() string

String implements the stringer interface

func (*DirectiveName) UnmarshalJSON

func (n *DirectiveName) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Unmarshaler interface

type DirectiveType

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

DirectiveType provides a strongly typed enum for directive types

func (DirectiveType) MarshalJSON

func (t DirectiveType) MarshalJSON() ([]byte, error)

MarshalJSON implements the Marshaler interface

func (DirectiveType) String

func (t DirectiveType) String() string

String implements the stringer interface

func (*DirectiveType) UnmarshalJSON

func (t *DirectiveType) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Unmarshaler interface

type Frame

type Frame struct {
}

Frame contains information that needs to be preserved during multiple continuous interactions with the skill.

type History

type History struct {
}

History contains the history of the conversation in a multi-turn interaction.

type Params

type Params struct {
	TargetDialogueState string      `json:"target_dialogue_state,omitempty"` // Possible values: "skill_intro", "TODO:?what else?"
	TimeZone            string      `json:"time_zone,omitempty"`
	Timestamp           int64       `json:"timestamp,omitempty"`
	Language            string      `json:"language,omitempty"`
	Locale              string      `json:"locale,omitempty"`
	DynamicResource     interface{} `json:"dynamic_resource,omitempty"`
	AllowedIntents      interface{} `json:"allowed_intents,omitempty"`
}

Params Contains information like time_zone, timestamp of the query, language, etc... One particular field here is target_dialogue_state this can be used to tell us what the user intended to do. In this particular case, if the field is equal to skill_intro, we need to return an introductory message from the skill. TODO:Add missing fields.

type Payload

type Payload struct {
	Text               interface{}       `json:"text,omitempty"` // may be string or []string for e.g. ui-hints
	Delay              *int              `json:"delay,omitempty"`
	Prompt             *string           `json:"prompt,omitempty"`
	DisplayImmediately *bool             `json:"displayImmediately,omitempty"`
	Title              *string           `json:"title,omitempty"`
	URL                *string           `json:"url,omitempty"`
	Payload            map[string]string `json:"payload,omitempty"`
}

Payload is the payload for the WebexAssistantDirective

type WebexAssistantDirective

type WebexAssistantDirective struct {
	Name    DirectiveName `json:"name"` // reply, speak, listen, ui-hint, display-web-view, clear-web-view, assistant-event
	Type    DirectiveType `json:"type"` // view, action
	Payload Payload       `json:"payload"`
}

WebexAssistantDirective is the response we need to sent back to Webex Assistant

type WebexAssistantHealthResponse

type WebexAssistantHealthResponse struct {
	Challenge string `json:"challenge,omitempty"`
	Status    string `json:"status,omitempty"`
}

WebexAssistantHealthResponse is the response required for Webex Assistant Health Checks on our skill.

type WebexAssistantMessage

type WebexAssistantMessage struct {
	// Text      []string `json:"text"`
	Text      string  `json:"text"`
	Context   Context `json:"context"`
	Params    Params  `json:"params"`
	Frame     Frame   `json:"frame"`
	History   History `json:"history"`
	Challenge string  `json:"challenge"`
}

WebexAssistantMessage is the message we receive in the encrypted request from Webex Assistant.

type WebexAssistantRequest

type WebexAssistantRequest struct {
	Signature string
	Message   string
}

WebexAssistantRequest is the encrypted request we receive from Webex Assistant.

type WebexAssistantResponse

type WebexAssistantResponse struct {
	Directives []WebexAssistantDirective `json:"directives"`
	Challenge  string                    `json:"challenge"`
}

WebexAssistantResponse is what we can send back to webex assistant.