PullString Platform Documentation

The PullString Platform was designed to let non-technical teams craft rich two-way conversational experiences, or bots. The resources here will let you learn more about what PullString can do for you and how you can use it to make your own chatbots and agents.

Guides    User Forums

Web API Reference

The PullString Web API provides a method for initiating and carrying on a conversation with a project authored in PullString Author. A new conversation is given a Universally Unique ID (UUID), which can be used to advance that conversation by delivering inputs associated with that UUID. The JSON response from the Web API describes a sequence of responses for the client to process in order. The primary endpoints of the API are:

Base URL

All PullString Web API endpoints use the same base URL. This URL includes an API version number to support major changes in the future.

https://conversation.pullstring.ai/v1

Authentication

Each PullString Web API request requires an access token to identify the PullString account holder making the request. This UUID is passed in the Authorization HTTP header of the request.

Additionally, when starting a new conversation, you must provide a Project ID to indicate which of your published PullString projects you want to converse with.

You can find both of these by signing into https://platform.pullstring.com/ and selecting the AccountWeb API Keys menu from the top navigation bar. You'll see your Web API Key listed at the top followed by a table of Web API Project IDs for each project that you've published. Hit the Copy button next to each UUID to copy it to your clipboard. (Note that you can also find the Project ID within the PullString Author application via ProjectProject PropertiesOptions.)

The Web API Keys page on https://platform.pullstring.com/

The Web API Keys page on https://platform.pullstring.com/

If you haven't published any of your projects to your account yet, then you can do this using PullString Author's Publish dialog.

/conversation

You can initiate a new conversation using the /conversation POST endpoint. This will return a UUID that you can use in subsequent calls to /conversation/<UUID> to advance that specific conversation.

HTTP Header

Field
Value
Description
Required?

Authorization

Bearer <API_KEY>

Provide the Web API key for your PullString account. See above for how to find this access token for your account.

Required

Content-Type

application/json

Indicates the format of the data in the POST body. This will generally be JSON, except when sending raw audio data.

Optional

Accept

application/json

Indicates the format of the response the client wishes to receive. Only JSON is supported.

Optional

JSON POST Body

Field
Description
Required?

project

The ID for the PullString project that you want to interact with. See above for how to find this UUID for your project.

Required

time_zone_offset

A value in seconds representing the offset in UTC. For example, PST would be -28800.

Optional

participant

A UUID from the participant field of a previous conversation. You can use this to preserve entity state across multiple conversations.

Optional

build_type

One of sandbox or staging. Indicates the use of content published as a Sandbox or Staging build. This build type is an option when publishing content in PullString Author. The default is to use Production content.

Optional

Example Request (curl)

curl "https://conversation.pullstring.ai/v1/conversation" -X POST -H "Authorization:Bearer 9fd2a189-3d57-4c02-8a55-5f0159bff2cf" -H "Content-Type:application/json" -H "Accept:application/json" --data-binary '{"project":"e50b56df-95b7-4fa1-9061-83a7a9bea372"}'

Response HTTP Header

Field
Value
Description

Location       

v1/conversation/<UUID>

Endpoint to be used to further the conversation, encoding the UUID of the conversation.

Here's an example response header:

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Accept, Transfer-Encoding, Content-Length
Access-Control-Allow-Methods: *
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location
Content-Type: application/json
Location: v1/conversation/b47707b5-9b05-4393-be70-2afc8cfdbd3d

JSON Response Body

Field
Description

outputs

List of JSON objects where each entry in the list represents a response that should be played by the client. See below for the specification of this object. Note, for audio responses, this means that it's possible to return multiple audio files that should be played in order.

timed_response_interval

A time in seconds after which a response might be generated without further input from the user. Clients that receive this field should set a timer and call the /conversation/<UUID> endpoint again after the specified number of seconds to receive any time-based responses. For this callback, your can simply provide an empty JSON post body, i.e., {}.
Note: It is not guaranteed that there will be outputs to return after the timed response interval has elapsed, so clients should be able to handle a JSON response body containing no outputs.

conversation

UUID of conversation, as used in the Location header to construct the conversation endpoint

participant

The UUID of the participant for the conversation, such as all entity values. You only need to be concerned with this UUID if you want to initiate several new conversations and preserve the same participant state across all of those conversations, i.e., to maintain persistent state on a per user or per device basis.

asr_hypothesis

The text hypothesis of the speech contained in audio, as submitted using content type audio/l16; rate=16000 as described below. This field is not present in other responses, and is present solely to aid in development when adopting this API. In particular, this should help when trying to determine if audio containing speech is being presented successfully.

last_modified

Time of content modification as an RFC 1123 formatted date.

etag

A unique identifier for the version of the content.

outputs JSON Object Description:

Field
Description
Type

type

One of dialog or behavior

all

id

The UUID for the output

all

text

The text for the line of dialog to respond to the user with.

dialog

uri

URI of an audio file associated with the line of dialog, in AAC, MP3, or WAV format.

dialog

duration

Floating point value representing the duration of the recorded dialog in seconds.

dialog

phonemes

List of phonene JSON objects, where a single phoneme object looks like:

{ "name": "phoneme_name", "seconds_since_start": seconds }

Examples of phoneme_name are "SIL", "M", "AE", "OW". The seconds value is a floating point number representing the number of seconds since the beginning of the dialog audio file when the phoneme is intended to represent what is being said.

dialog

character

The name of the character responding to the user.

dialog

user_data

Optional arbitrary string data that was associated with the dialog line within PullString Author. This can be used to pass custom per-line information, such as an animation clip to play.

dialog

behavior

The name of the behavior, e.g., volume_up. You can create custom behaviors for your application within PullString Author.

behavior

parameters

A dictionary of parameters associated with the behavior, specified as a key/value dictionary. Here's an example showing various possible types that can be expressed:

{
  "behavior": "behavior_name",
  "parameters": {
     "strparam": "hello",
     "numparam": 1.1,
     "boolparam": True,
     "listparam": [ "one", "two", "three" ],
     "dictparam": {
        "key1": "hello again",
        "key2": 1
     }
  }
}

behavior

Here's an example JSON response body showing a simple text dialog response followed by a behavior. The client should process the responses in order, i.e., the text response first then the behavior.

{
  "outputs": [
    {
      "type": "dialog",
      "text": "Let's turn the volume up on this place!",
      "character": "Fred"
    },
    {
      "type": "behavior",
      "behavior": "volume_up"
    }
  ],
  "conversation": "b47707b5-9b05-4393-be70-2afc8cfdbd3d",
  "participant": "c3d32d03-a845-4175-aeb4-b6f518b1f434",
  "etag": "1431b1a09f669c893bc53d1880ccce28",
  "last_modified": "Mon, 18 Apr 2016 16:38:11 UTC"
}

Here's another example JSON response body showing a single audio response with M4A audio file and a description of the phonemes for the dialog (the list of phonemes is truncated for clarity). Note that if multiple dialog responses are returned, the client should play each audio file one after the other, in the order specified.

{
  "outputs": [
    {
      "type": "dialog",
      "text": "Attention Zookeepers! When speaking to animals, please remember to hold down your microphone buttons, then let go when you're done. That is all.",
      "uri": "http://storage.toytalk.com/9/7/f/97f65748e251105a9e2f67a97a9badec_dbe0f6e4-f0a8-4cff-83eb-b72d787b81fb_1.m4a",
      "duration": 11.24,
      "phonemes": [
        {
          "name": "SIL",
          "seconds_since_start": 0
        },
        {
          "name": "AH",
          "seconds_since_start": 0.019
        },
        {
          "name": "SIL",
          "seconds_since_start": 0.904
        }
      ],
      "character": "Tiger Cub"
    }
  ],
  "timed_response_interval": 10,
  "conversation": "b47707b5-9b05-4393-be70-2afc8cfdbd3d",
  "participant": "c3d32d03-a845-4175-aeb4-b6f518b1f434",
  "etag": "1431b1a09f669c893bc53d1880ccce28",
  "last_modified": "Mon, 18 Apr 2016 16:38:11 UTC"
}

Phonemes Codes

The following list of phonemes is supported: AA, AE, AH, AO, AW, AY, B, CH, D, DH, EH, ER, EY, F, G, HH, IH, IY, JH, K, L, M, N, NG, OW, OY, P, R, S, SH, T, TH, UH, UW, V, W, Y, Z, ZH, SIL.

Handling Time-Based Responses

Clients that receive a timed_response_interval in their JSON response should start a timer and then issue another API request after the specified elapsed time in order to support time-based responses. That API request can be an empty JSON dictionary, i.e., {}, to signal that the request is not based upon any user-initiated action.

/conversation/<UUID>

You can advance a conversation using the /conversation/<UUID> POST endpoint, where UUID is the value of the conversation field from the JSON response of an earlier call to /conversation or /conversation/<UUID>.

HTTP Header

Field
Values
Description
Required?

Authorization

Bearer <API_KEY>

Provide the Web API key for your PullString account. See above for how to find this access token for your account.

Required

Content-Type

One of application/json or audio/l16; rate=16000

Indicates the format of the POST body data. If unspecified then JSON is assumed.

Optional

Accept                       

application/json

Indicates the format of the response the client wishes to receive. Only JSON is supported.

Optional

Transfer-Encoding

chunked

This is useful when sending audio data of unknown length, such as streaming audio while it is being recorded.

Optional

Query String Parameters

Field
Value
Description
Required?

language

<language>

Language to use for speech recognition, using an RFC 1766 Language Tag. "en-US" is used if none is specified. Ignored if content type is not "audio/l16; rate=16000".

Optional

locale

<locale>

Locale used to infer languagee.g., en_US. Ignored if language is present.

Optional

restart_if_modified

true or false

Restart this conversation if a newer version of the project has been published. Default value is true.

Optional

POST Body -- Content Type: application/json

The following inputs can be sent to the /conversation/<UUID> endpoint:

  • text = textual user input, such as something the user has typed or a speech recognition hypothesis
  • intent = the name of an intent that represents user input, e.g. see Intents
  • activity = a named activity to initiate, e.g., see Organizers
  • event = a named event to trigger conversation, e.g., see Events.
  • set_entities = change the value of one or more entities, e.g., see Entities
  • get_entities = query the current value of one or more entities, e.g., see Entities
  • goto = jump the conversation to a specific response in the content (for debugging)

POST Body Object Descriptions

Field
Description

text

String containing the text input from a user to advance the PullString driven conversation.

{
  "text": "Hello there, how are you?"
}

intent

String containing the name of an intent representing user input to advance the PullString driven conversation. You can also perform slot filling of entities by providing a set_entities field (see below).

{
  "intent": "Intent Name"
}

activity

The name or UUID of the activity to switch to.

{
  "activity": "2e9717b5-8bf2-5a3f-c26a-5bfd32edb258"
}

event

A description of the event, in the following format. Note that the dictionary of parameters is optional depending upon the specific event.

{
  "event": {
    "name": "event_name",
    "parameters": {
       "strparam": "hello",
       "numparam": 1.1,
       "boolparam": True
    }
  }
}

set_entities

Contains a dictionary of entities and their new values, such as:

{
  "set_entities": {
    "Player Score": 4,
    "Winner": false,
    "Name": "Fred"
  }
}

Numeric values are used for counters, boolean values for flags, and string values for labels.

get_entities

List of label, counter, and/or flag names that you want to discover the current value for. For example:

{
  "get_entities": [
    "Player Score",
    "Winner",
    "Name"
  ]
}

goto

The UUID of the response to immediately jump to. You can find this UUID by selecting a response in PullString Author, selecting Copy, and then pasting the clipboard into a text-based application like Terminal or TextEdit on a Mac. This is intended for debugging purposes only.

{
  "goto": "9f25a7b5-0e28-790d-6f7b-8ff39de8b35f"
}

Here is an example text JSON request:

curl "https://conversation.pullstring.ai/v1/conversation/b47707b5-9b05-4393-be70-2afc8cfdbd3d" -X POST -H "Authorization:Bearer 9fd2a189-3d57-4c02-8a55-5f0159bff2cf" -H "Content-Type:application/json" -H "Accept:application/json" --data-binary '{ "text": "okay, play rock paper scissors" }'

And an example of using the set_entities input type:

curl "https://conversation.pullstring.ai/v1/conversation/b47707b5-9b05-4393-be70-2afc8cfdbd3d" -X POST -H "Authorization:Bearer 9fd2a189-3d57-4c02-8a55-5f0159bff2cf" -H "Content-Type:application/json" -H "Accept:application/json" --data-binary '{ "set_entities": { "Reached Goal": true, "Number of Attempts": 2.0 } }'

And an example of using the get_entities input type:

curl "https://conversation.pullstring.ai/v1/conversation/b47707b5-9b05-4393-be70-2afc8cfdbd3d" -X POST -H "Authorization:Bearer 9fd2a189-3d57-4c02-8a55-5f0159bff2cf" -H "Content-Type:application/json" -H "Accept:application/json" --data-binary '{ "get_entities": ["Reached Goal", "Number of Attempts"] }'

POST Body -- Content Type: application/json

The response to most conversational events has the same structure as the response to initiating a conversation, as described above. Nothing notable is expressed in the headers and the body has the same format.

Conversation UUID May Change

Note that the /conversation/<UUID> endpoint can return a JSON response that includes a different conversation UUID value in the conversation field. Clients should note this change in conversation UUID and send this new UUID in future calls for that conversation. If you don't do this, you may receive a 404 response when using an expired conversation ID.

Responses to set_entities and get_entities requests will contain an entities section that looks as follows, with an entry for each entity that was requested (and which is defined in the appropriate PullString project).

{
  "conversation": "24588ccd-bf2a-4fd6-9e3b-78b4dc9114be",
  "participant": "0e1a6062-b494-4e38-87c9-45ad59e9f23c",
  "entities": {
    "Number of Attempts": 2.0,
    "Reached Goal": true,
    "Favorite Color": "green"
  },
  "etag": "1431b1a09f669c893bc53d1880ccce28",
  "last_modified": "Mon, 18 Apr 2016 16:38:11 UTC"
}

POST Body -- Content Type: audio/l16; rate=16000

The post body should consist entirely of audio in the format defined for content type "audio/l16; rate=16000" in RFC 2586. That is to say, linear 16-bit Pulse Code Modulation (PCM) mono audio with 16,000 samples per second.

The post body can be either fully specified at the time of the request or streamed using the "chunked" HTTP Transfer Coding as specified in RFC 2616.

Other rates besides 16,000 can be specified and the audio will be resampled at 16,000 Hz via a very basic linear interpolation. This is not recommended! The quality is noticeably reduced as is the speech recognition accuracy. This automatic resampling is intended for testing purposes only.

Here's an example request showing how you can send audio as input. This assumes there is a file named "audio" in the current working directory which contains properly formatted audio.

curl "https://conversation.pullstring.ai/v1/conversation/b47707b5-9b05-4393-be70-2afc8cfdbd3d" -X POST -H "Authorization:Bearer 9fd2a189-3d57-4c02-8a55-5f0159bff2cf" -H "Content-Type:audio/l16; rate=16000" -H "Accept:application/json" -H "Transfer-Encoding: chunked" --data-binary @audio

/participant/<UUID>

The participant endpoint lets you manipulate the state for a given participant ID (as returned by the /conversation endpoint). Currently this just supports the ability to delete the state for a given participant. This can be useful for experiences that operate in a compliant space, such as COPPA, and require the ability to delete all data stored by PullString for a given conversation.

Deleting all the state for a given participant ID can be done by sending a DELETE HTTPS request, passing the standard PullString authentication key in the HTTP header. Upon success, the endpoint will return a 200 return code and an empty JSON dictionary, i.e., "{ }".

Example Request (curl)

curl https://conversation.pullstring.ai/v1/participant/f7929b14-462c-98ab-363e-72e22a4f6991 -H "Authorization: Bearer 9fd2a189-3d57-4c02-8a55-5f0159bff2cf" -X DELETE

/manifest

In certain cases, it may be desirable to know all of the assets that are used by a given conversational experience. For example, a game that uses the PullString Web API to enable conversations with its characters may want to download and locally cache all of the audio files for each line of dialog ahead of time. This may be done to reduce playback latency or perform some preprocessing on the assets. The /manifest endpoint is provided to solve just this need. The manifest is organized by line of content so that you have the correlation between a given line of output (i.e., a response or behavior) and any audio, image, or video assets associated with that piece of content.

HTTP Header

Field
Value
Description
Required?

Authorization

Bearer <API_KEY>

Provide the Web API key for your PullString account. See above for how to find this access token for your account.

Required

Content-Type

application/json

Indicates the format of the data in the POST body. This will generally be JSON, except when sending raw audio data.

Optional

Accept

application/json

Indicates the format of the response the client wishes to receive. Only JSON is supported.

Optional

JSON POST Body

Field
Description
Required?

project

The ID for the PullString project that you want to interact with. See above for how to find this UUID for your project.

Required

Example Request (curl)

curl "https://conversation.pullstring.ai/v1/manifest" -X POST -H "Authorization:Bearer 9fd2a189-3d57-4c02-8a55-5f0159bff2cf" -H "Content-Type:application/json" -H "Accept:application/json" --data-binary '{"project":"e50b56df-95b7-4fa1-9061-83a7a9bea372"}'

JSON Response Body

last_modified

Time of content modification as an RFC 1123 formatted date.

etag

A unique identifier for the version of the content.

manifest

A list of manifest objects, one per line of content, that describe all of the assets associated with that line of content. See below for the description of this object.

manifest JSON Object Description:

Field
Description

id

The UUID for the output, i.e.,. a response or a behavior. The remaining fields of the object describe all of the assets that are referenced by this specific line of content.

runtime_audio

The URL for the audio file containing the dialog for a response. This is the runtime audio format, such as MP3, M4A, or WAV, depending upon your project settings.

standard_wave_audio

The URL for the standard format WAV file containing the dialog for a response. The format of this file is always uncompressed 16,000 samples/sec 16-bit Linear PCM.

duration

The duration (secs) of the audio for this line, if present.

phonemes

The list of phonemes for this line, if present. This follows the same format as returned by the /conversation endpoint.

video_file

For projects that support video associated with a line of dialog, this field provides the URL to that video file.

user_data

The user data field associated with the response. User data is a way to pass along information with a line of dialog to an external system, such as animation data for a game engine to play. It is included in the manifest as it may reference assets in the external animation system.

media_urls

For outputs that are behaviors, this field lists all of asset URLs that are referenced by any of the parameters of that behavior. For example, the builtin Send Image behavior may include a reference to the image to be displayed, or a project-specific custom behavior may include references to several image, video, or audio assets.

The following example illustrates the JSON output of the /manifest endpoint, with the actual asset URLs redacted for clarity.

{
  "etag": "a2f6b45e4c06894d86eb5f14bd81cedd",
  "last_modified": "Mon, 17 Apr 2017 13:48:34 UTC",
  "manifest": [
    {
      "id": "6d4e2552-1202-4abb-9062-c839929cb2df",
      "runtime_audio": "<url-to-mp3>",
      "standard_wave_audio": "<url-to-wav>"
    },
    {
      "id": "92220fef-3234-41fe-bb24-4e8cb9f94a1d",
      "media_urls": [
        "<url-to-image>",
        "<url-to-another-image>"
      ]
    },
    ...
  ]
}

Error Handling

If there was an error while processing your request, the response body will contain JSON data that describes the HTTP status code and an explanation of the error. This can happen, for example, if you provide an invalid API key or an unknown conversation UUID is used to construct an endpoint. The error status is returned as follows:

{
   "error" : {
      "status" : 403,
      "message" : "Invalid Authorization Bearer Token: &quot;2e6de497-f9c9-4252-ac66-e945fc957c6&quot;"
   }
}

Cross Origin Resource Sharing

The OPTIONS method for CORS is supported on all of the endpoints above. All responses from all endpoints include the following CORS related headers, which should allow usage from javascript within a web browser. The header values may be more specific based on the incoming request.

Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Accept, Transfer-Encoding, Content-Length
Access-Control-Allow-Methods: *
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location

Web API Reference


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.