Start an action, or submit its last canvas

POST

/v1/threads/{id}/action-steps

curl --request POST \
  --url https://api.threadkite.app/v1/threads/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/action-steps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "action": "example", "values": { "additionalProperty": null }, "state": "example", "button": "example" }'

• Threadkite API

With only action, the first canvas. With values (and the state and button the last step gave), the next canvas or, when it is done, the action run. A provider’s refusal comes back as the canvas again with its errors.

Authorizations

• api_key
  threads:write

Parameters

Path Parameters

id

required

string format: uuid

Request Body^required

Media typeapplication/json

object

action

required

The action’s key

string

>= 1 characters <= 200 characters

values

The last canvas’s values, by field id. Leave out to start the action. Money in minor units

object

key

additional properties

Any of:

string

string

<= 5000 characters

number

number

boolean

boolean

string

string

nullable

state

The state the last step gave, as it was

string

nullable <= 4096 characters

button

string

nullable <= 64 characters

Responses

200

Media typeapplication/json

One of:

object

object

status

required

string

Allowed values: form

canvas

required

A form to fill in, drawn by Threadkite from its components

object

title

required

string

nullable

components

required

Array

<= 50 items

One of:

object

object

type

required

string

Allowed values: text

text

required

string

>= 1 characters <= 2000 characters

style

required

string

default: body

Allowed values: body muted heading error

object

object

type

required

string

Allowed values: details

items

required

Array<object>

>= 1 items <= 30 items

object

label

required

string

>= 1 characters <= 120 characters

value

required

string

<= 2000 characters

object

object

type

required

string

Allowed values: divider

object

object

type

required

string

Allowed values: link

label

required

string

>= 1 characters <= 120 characters

url

required

string format: uri

<= 2000 characters

object

object

type

required

string

Allowed values: input

id

required

string

/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/

label

required

string

>= 1 characters <= 120 characters

inputType

required

string

default: text

Allowed values: text secret textarea number money email phone date

required

required

boolean

value

Any of:

string

string

<= 5000 characters

number

number

placeholder

string

nullable <= 120 characters

hint

string

nullable <= 2000 characters

min

number

nullable

max

number

nullable

object

object

type

required

string

Allowed values: select

id

required

string

/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/

label

required

string

>= 1 characters <= 120 characters

options

required

Array<object>

>= 1 items <= 100 items

object

value

required

string

>= 1 characters <= 200 characters

label

required

string

>= 1 characters <= 120 characters

required

required

boolean

value

string

nullable <= 200 characters

hint

string

nullable <= 2000 characters

object

object

type

required

string

Allowed values: checkbox

id

required

string

/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/

label

required

string

>= 1 characters <= 120 characters

value

boolean

nullable

hint

string

nullable <= 2000 characters

object

object

type

required

string

Allowed values: item

id

required

string

/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/

label

required

string

>= 1 characters <= 120 characters

required

required

boolean

value

string format: uuid

nullable

hint

string

nullable <= 2000 characters

submitLabel

required

No submit button when null

string

nullable

errors

required

The last submit’s problems, by field id (_ for the whole form)

object

key

additional properties

string

state

required

string

nullable

object

object

status

required

string

Allowed values: done

run

required

object

id

required

string format: uuid

threadId

required

string format: uuid

nullable

contactId

required

string format: uuid

nullable

action

required

object

key

required

string

label

required

string

source

required

object

kind

required

string

Allowed values: connection app

id

required

The connection’s id, or the app installation’s

string format: uuid

name

required

string

capability

required

string

nullable

card

required

object

title

required

string

subtitle

required

string

nullable

tone

required

string

Allowed values: neutral success warning danger

lines

required

Array<object>

object

label

required

string

value

required

string

body

required

string

nullable

smallPrint

required

Array<string>

customerMessage

required

What to send the customer, when the action gives something

object

text

required

string

subject

required

string

nullable

editable

required

boolean

url

required

Where it opens in the other system

string

nullable

sentMessageId

required

Once sent to the customer

string format: uuid

nullable

createdBy

required

One of:

object

object

id

required

string

name

required

string

createdAt

required

string format: date-time

Example

{
  "status": "form",
  "canvas": {
    "components": [
      {
        "type": "text",
        "style": "body"
      }
    ]
  }
}

400

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

401

Missing or invalid API key

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

402

The organisation is on the Free plan (code upgrade_required)

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

feature

required

The feature that needs Pro

string

nullable

Allowed values: extraSeats connections aiAssistant aiReplies rules fullReports api inboxes bulkMessages videoMessages

upgradePath

required

Where to upgrade or pay, in the web app

string

Example

{
  "statusCode": 402,
  "code": "upgrade_required",
  "message": "Connections are part of Pro. Upgrade to connect texts, calls and more.",
  "feature": "extraSeats",
  "upgradePath": "/settings/billing"
}

403

The key does not have the scope (or the person the permission)

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

404

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

422

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

429

Rate limit reached

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

retryAfter

required

Seconds until another request will be accepted

number

Example

{
  "statusCode": 429,
  "code": "rate_limited",
  "message": "Too many requests. Each key can make 120 requests a minute; try again in 12 seconds.",
  "retryAfter": 12
}

502

The app or provider did not answer, or answered with something we can’t show

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}