Skip to content

_conversationWebhooks.md

Latest commit

 

History

History
351 lines (272 loc) · 12.3 KB

_conversationWebhooks.md

File metadata and controls

351 lines (272 loc) · 12.3 KB

Conversation Webhooks

The Conversation Webhook is resource, that represents a url endpoint that will be called for certain actions called triggers. Examples of triggers include conversation updates, response creation, and fallback suggested. Each webhook belongs to an client/API key and all conversations created by that client will be linked to webhooks of the same client.

API Schemas

ConversationWebhook

Field Type Description Readable? Writable? Required? Default
id ObjectId The ID of the conversation webhook this resource represents. Yes No No
name String The user friendly name of the webhook. Has no functional value but useful for describing the webhook's purpose. Yes Yes No
target String A valid url that the webhook payload will be sent to. Yes Yes Yes
secret String A secret key that will be used as a http header to ensure the sender is our system. Yes No No
version String A string indicating the API version. (e.g. 'v1') Yes No No 'v1'
triggers List<String> The list of triggers this webhook is subscribed to. Yes Yes Yes
createdAt DateTime The datetime string of when this webhook was created. Yes No No
updatedAt DateTime The datetime string of when this webhook was last updated. Yes No No

Webhook Schemas

ConversationSlotUpdate

Field Type Description
name String The name of the slot being updated.
action String The action to take on the slot. Either 'set' or 'push' for scalar or list types respectively.
value[1] Any[2] The new value being set for this slot. Only exists if the action is 'set'.
values[1] List<Any>[2] The list of values being added to current list of values for this slot. Only exists if the action is 'push'.

ConversationStageUpdate

Field Type Description
name String The name of the stage that is being added or removed from the stage list.
action String The action to take for this stage. Will be either 'add' or 'remove'.
reasons List<String> A list of reasons why this stage occurred. A list of either intent names or slot comparisons.

ConversationUpdates

Field Type Description
slots List<ConversationSlotUpdate>[^] Conversation slot updates.
stages List<ConversationStageUpdate>[^] Conversation stage updates.
  1. value and values are mutually exclusive. Only one will exist at a time and the other will be undefined.
  2. See slots for more info on each slot and it's type.

Conversation Webhook Overview

Webhooks are used to receive updates for conversations available on the API. These updates are used to notify when a conversations state has changed or when an action like sending a response should be taken. To use webhooks, create a webhook with the triggers that you want to listen for and the target set to an endpoint you control in your system.

Response Created

Response Created Example

{
    "trigger": "response:created",
    "id": "5c09a4416241ea2c293275b8",
    "response": {
        "text": "Can you tell me more about the location you're interested in?"
    }
}

Trigger

response:created

Description

This trigger is called when a new response for a conversation has been created. Responses are generated by Structurely for a message added to the relevant conversation. Use this event to know when and what to respond to a lead with after a lead sends a message.

Payload

Parameter Type Description
trigger String The trigger that triggered this webhook.
id ObjectId The id of the conversation.
response Message[^] A truncated Message object containing only the text field. The text was generated by Structurely to be sent as a response to a message created in this conversation.

Conversation Updated

Conversation Updated Example

{
    "trigger": "conversation:updated",
    "id": "5c09a4416241ea2c293275b8",
    "updates": {
        "slots": [
            {
                "name": "email",
                "action": "set",
                "value": "jdoe@example.com"
            },
            {
                "name": "address",
                "action": "push",
                "values": ["123 Main St.", "456 North Ave."]
            }
        ],
        "stages": [
            {
                "name": "not_responded",
                "action": "remove",
                "reasons": []
            },
            {
                "name": "responded",
                "action": "add",
                "reasons": []
            },
            {
                "name": "needs_follow_up",
                "action": "add",
                "reasons": ["financing_status is false"]
            }
        ]
    }
}

Trigger

conversation:updated

Description

This trigger is called when the convsersation object is updated. It will include the updates to the slots and stages. Use this to maintain state between your system and the Structurely API without polling.

Payload

Parameter Type Description
trigger String The trigger that triggered this webhook.
id ObjectId The id of the conversation.
updates ConversationUpdates[^] The updates to the conversation stages and slots.

List Conversation Webhooks

curl 'https://api.structurely.com/v1/conversationWebhooks?name=My%20&trigger=response:created' \
    -H 'X-Api-Authorization: myapikey'

The above command returns JSON structured like this:

{
    "_metadata": {
        "collection": "conversationWebhooks",
        "limit": 10,
        "offset": 0,
        "total": 2
    },
    "conversationWebhooks": [
        {
            "id": "5ceec43ce1b5b412ba9d0e73",
            "name": "My Webhook",
            "target": "https://www.example.com/webhooks/endpoint",
            "secret": "nLjs7uu5AvQfTjqXpXHnSOfj0h8bvc0w0eeZNWgFR1pJo9Gb",
            "version": "v1",
            "triggers": ["conversation:updated", "response:created"],
            "updatedAt": "2019-05-29T12:41:16.000Z",
            "createdAt": "2019-05-29T12:41:16.000Z"
        },
        {
            "id": "5ceed39ce1b5b412ba9d0e74",
            "name": "My Other Webhook",
            "target": "https://hooks.example.com/structurely/response_created",
            "secret": "ZQjevvm3JW7Y8drTROfoRokuYR75BPpAq7NDj0MYkQS2pQVa",
            "version": "v1",
            "triggers": ["response:created"],
            "updatedAt": "2019-05-29T13:48:20.000Z",
            "createdAt": "2019-05-29T13:48:20.000Z"
        }
    ]
}

This endpoint returns all webhooks that match the provided parameters. The objects returned will match all the provided parameters.

HTTP Request

GET https://api.structurely.com/v1/conversationWebhooks

Query Parameters

Parameter Type Description Required? Default
limit Integer[1,100] The number of results to return No 10
offset Integer[0,) Indicates the number of results to skip No 0
sort[1] String A comma separated list of fields to sort by No -createdAt
name[2] String A partial or full name of a webhook to search No None
target String A exact URL target of a webhook to match No None
trigger String An exact trigger that must be in a matched webhooks triggers list. Matched webhooks must include this trigger exactly. Matched webhooks may include other triggers. No None
  1. The sort string allows multiple fields with left to right precedence with optional - or + for controlling ascending and descending order
  2. String search fields use a case insensitive partial filter that can match any part of the string unless otherwise noted
Be sure to replace myapikey with your API key.

Create Conversation Webhook

curl 'https://api.structurely.com/v1/conversationWebhooks' \
  -X POST \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "My Webhook", "target": "https://www.example.com/webhooks/endpoint", "triggers": ["conversation:updated", "response:created"] }'

The above command returns JSON structured like this:

{
    "id": "5ceec43ce1b5b412ba9d0e73",
    "name": "My Webhook",
    "target": "https://www.example.com/webhooks/endpoint",
    "secret": "nLjs7uu5AvQfTjqXpXHnSOfj0h8bvc0w0eeZNWgFR1pJo9Gb",
    "version": "v1",
    "triggers": ["conversation:updated", "response:created"],
    "updatedAt": "2019-05-29T12:41:16Z",
    "createdAt": "2019-05-29T12:41:16Z"
}

This endpoint creates and returns a new conversation webhook.

HTTP Request

POST https://api.structurely.com/v1/conversationWebhooks

Body Parameters[^]

Parameter Type
name String
target String
triggers List<String>
Be sure to include the header `Content-Type: application/json` with your request.

Get Conversation Webhook

curl 'https://api.structurely.com/v1/conversationWebhooks/5ceec43ce1b5b412ba9d0e73' \
    -H 'X-Api-Authorization: myapikey'

The above command returns JSON structured like this:

{
    "id": "5ceec43ce1b5b412ba9d0e73",
    "name": "My Webhook",
    "target": "https://www.example.com/webhooks/endpoint",
    "secret": "nLjs7uu5AvQfTjqXpXHnSOfj0h8bvc0w0eeZNWgFR1pJo9Gb",
    "version": "v1",
    "triggers": ["conversation:updated", "response:created"],
    "updatedAt": "2019-05-29T12:41:16Z",
    "createdAt": "2019-05-29T12:41:16Z"
}

HTTP Request

GET https://api.structurely.com/v1/conversationWebhooks/<id>

URL Parameters

Parameter Description
id The ID of the conversation webhook to retrieve

Update Conversation Webhook

curl 'https://api.structurely.com/v1/conversationWebhooks/5ceec43ce1b5b412ba9d0e73' \
    -X PATCH \
    -H 'X-Api-Authorization: myapikey' \
    -H 'Content-Type: application/json' \
    -d '{ "name": "My Cool Webhook", "target": "https://hooks.example.com/structurely/conversation_updated", "triggers": ["conversation:updated"] }'

The above command returns JSON structured like this:

{
    "id": "5ceec43ce1b5b412ba9d0e73",
    "name": "My Cool Webhook",
    "target": "https://hooks.example.com/structurely/conversation_updated",
    "secret": "nLjs7uu5AvQfTjqXpXHnSOfj0h8bvc0w0eeZNWgFR1pJo9Gb",
    "version": "v1",
    "triggers": ["conversation:updated"],
    "updatedAt": "2019-05-29T12:41:16Z",
    "createdAt": "2019-05-29T12:41:16Z"
}

HTTP Request

PATCH https://api.structurely.com/v1/conversationWebhooks/<id>

URL Parameters

Parameter Description
id The ID of the conversation webhook to update

Body Parameters[^]

Parameter Type
name String
target String
triggers List<String>
Be sure to include the header `Content-Type: application/json` with your request.

Delete Conversation Webhook

curl 'https://api.structurely.com/v1/conversationWebhooks/5ceec43ce1b5b412ba9d0e73' \
    -X DELETE
    -H 'X-Api-Authorization: myapikey'

The above command returns an empty response with the status 204 if successful

HTTP Request

DELETE https://api.structurely.com/v1/conversationWebhooks/<id>

URL Parameters

Parameter Description
id The ID of the conversation webhook to delete