Forms, Fields and Results

Forms are containers of fields that may be added to the conversation by agents or automations. Forms are defined per-organization, and assigned to the various conversation categories.

See the Categories and Forms chapter of the Provisioning Guide for more information.

Forms can be added to or removed from a conversation for the currently active category, and processed into the array of results for the conversation. All form-related actions are best performed by posting messages into the conversation.

Activate a Form

You can programmatically activate a form for a conversation by POSTing a form type message to the conversation. The text of the message can be anything but is probably the form name, provided it is prefixed by a plus-sign (+) Example:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "form",
    "text": "+Proefrit",
    "meta": {
      "form": "590c76bdde1b762f2113e81c",
      "categoryIndex": 1
    }
}

This will add the form to the second category for the conversation. The meta properties must specify at least a form ID, and an optional categoryIndex (indices, the category slots for the organization, range from 0-9) or a category name. The category the form is added for defaults to the currently activate category for the conversation.

The form must be assigned to the category in the Organization's organization.categories settings.

Remove a form

Likewise, a currently active form can be removed from a category by prefixing the message text with a minus-sign (-). In the example below, the form will be removed from the currently active category (since categoryIndex or category are not specified as a meta property).

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "form",
    "text": "-Proefrit",
    "meta": {
      "form": "590c76bdde1b762f2113e81c"
    }
}

Set a Field value

In its essence, a form instance inside a conversation is just a bag of field values (key/value pairs). To set a field using a message, optionally prefix the message text with a dot (.) and specify the value after the first whitespace:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "field",
    "text": ".rating 8.3",
    "meta": {
      "field": "590c76bdde1b762f2113e81d",
      "form": "590c76bdde1b762f2113e81c"
    }
}

Meta properties should at least specify a field ID and a form ID. Like we've seen before, since no meta.categoryIndex or meta.category is specified, the currently active category is assumed.

To clear a field value that was set earlier, just omit the value:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "field",
    "text": ".rating",
    "meta": {
      "field": "590c76bdde1b762f2113e81d",
      "form": "590c76bdde1b762f2113e81c"
    }
}

The form now no longer has a value for the rating field.

Contact Profile Fields

In addition to forms, any fields in the contact profile may be set using a field-type message.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "field",
    "text": ".givenName John"
}

Here are the available fields:

When updating a profile field, no meta data is required.

Listing Forms

While processing webhooks or querying the API, your application has full access to all category form instances that were added to conversation.

Request: GET /v2/conversations/590bd49f458b716046347f47

Response: 200 OK

{
    "id": "590bd49f458b716046347f47",
    "category": "Used Car",
    "categoryIndex": 1,
    "forms": [
        {
            "name": "Test Drive",
            "form": "590c76bdde1b762f2113e81c",
            "type": "topic",
            "state": "completed",
            "labels": [
                "isLead"
            ],
            "category": "Used Car",
            "categoryIndex": 1,
            "values": {
                "rating": "8.3"
            }
        }
    ],
    ... other conversation attributes ...
}

Form state

Each form instance can be in state active or completed when all required form fields have corresponding values specified. Whereas an active form instance is considered being worked on, a completed form is ready to be processed into a results message.

Form labels

A form definition can have form labels specified: custom tags that are recorded in conversation.forms conversation.results and type: results messages. These labels are recorded throughout the result lifecycle for reporting purposes.

Processing Completed Forms

Once a form is completed, the /process command message will process all completed form instances for all categories. To process one specific completed form in the conversation, specify the form ID as meta.form

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "command",
    "text": "/process",
    "meta": {
        "form": "590c76bdde1b762f2113e81c"
    }
}

Aliases: /send /dispatch /results

This command accomplishes the following for each completed form:

1. The form instance is removed from the conversation.forms list, and pointer to the results message is added to the conversation.results list;
2. A results-type message for the form values is added to the conversation;
3. If the form definition has form.notifyEmails specified, email notifications are sent.

Conversation Results

As a result of executing the /process command, all completed forms are removed from the conversation's active forms list. A results-type message is added to the conversation, and the message ID and form are added to the conversation's results list. If you retrieve the conversation you'll see the changes:

Request: GET /v2/conversations/590bd49f458b716046347f47 Response: 200 OK

{
    "id": "590bd49f458b716046347f47",
    "category": "Used Car",
    "categoryIndex": 1,
    "forms": [],
    "results": [
        {
            "name": "Test Drive",
            "form": "590c76bdde1b762f2113e81c",
            "labels": [
                "isLead"
            ],
            "category": "Used Car",
            "categoryIndex": 1,
            "message": "59ac3cf257615f431a1a0ec9"
        }
    ],
    ... other conversation attributes ...
}

Results Messages

Webhook processors and API users have easy access to all processed forms by listening on webhooks or retrieving messages through the API. A results-type message serves as a container for all completed forms and field values that were processed as a result of the /process command.

For example, to fetch all results messages for a particular conversation in reverse order by creation date:

Request: GET /v2/conversations/590bd49f458b716046347f47/messages?type=results&sort=-createdAt

Response: 200 OK

[
    {
        "organization": "590bcf50458b716046347f36",
        "conversation": "590bd49f458b716046347f47",
        "type": "results",
        "contact": "59ac346e92da1c3b2a86ecce",
        "text": "/send success - forms processed",
        "actions": [],
        "results": [
            {
                "name": "Test Drive",
                "form": "590c76bdde1b762f2113e81c",
                "state": "completed",
                "type": "topic",
                "labels": [
                    "isLead"
                ],
                "category": "Used Car",
                "categoryIndex": 1,
                "values": {
                    "rating": "8.3"
                }
            }
        ],
        "createdAt": "2017-09-03T17:33:38.078Z",
        "updatedAt": "2017-09-03T17:33:38.078Z",
        "id": "59ac3cf257615f431a1a0ec9"
    }
]

Extend your queries with additional filters and population as outlined in the chapter Fetching Resources. For example, to fetch all results messages across all organizations for a specific day, with contact details expanded:

Request: GET /v2/messages?createdAt=>2017-09-03,<=2017-09-04&type=results&populate=contact

Response: 200 OK

[
    {
        "id": "59ac405787709d4566589dd9",
        "organization": "590bcf50458b716046347f36",
        "conversation": "590bd49f458b716046347f47",
        "type": "results",
        "contact": {
            "id": "59ac346e92da1c3b2a86ecce",
            "profile": {
                "additionalName": null,
                "email": "alice@example.com",
                "familyName": "Johnson",
                "givenName": "Alice",
                "initials": null,
                "name": "Alice Johnson",
                "address": {}
            },
            ... other contact fields ...
        },
        "text": "/send success - forms processed",
        "actions": [],
        "results": [
            {
                "name": "Test Drive",
                "form": "590c76bdde1b762f2113e81c",
                "state": "completed",
                "type": "topic",
                "labels": [
                    "isLead"
                ],
                "category": "Used Car",
                "categoryIndex": 1,
                "values": {
                    "rating": "8"
                }
            }
        ],
        "createdAt": "2017-09-03T17:48:07.332Z",
        "updatedAt": "2017-09-03T17:48:07.332Z"
    }
]

Please note that field values for contact profile changes are not included in results messages.

Report Messages

Like results-type messages, messages typed report should also contain a "results" array property to store key-value pairs. But while a results message generated by the system when triggered by a /send command, a report message is typically created by a bot or automation for displaying a summary of previous tasks accomplished.

For example, an automation might create the following report message and have it displayed as a card with key-value pairs in a chat application:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

Response: 201 Created

[
    {
        "organization": "590bcf50458b716046347f36",
        "conversation": "590bd49f458b716046347f47",
        "type": "report",
        "contact": "59ac346e92da1c3b2a86ecce",
        "text": "Performance Review",
        "actions": [],
        "results": [
            {
                "name": "Agent Performance",
                "values": {
                    "score": "8.3"
                }
            }
        ],
        "createdAt": "2017-09-03T17:33:38.078Z",
        "updatedAt": "2017-09-03T17:33:38.078Z",
        "id": "59ac3cf257615f431a1a0ec9"
    }
]

Emails Sent

For each form result that is processed, one or more notification emails will be sent if the corresponding form definition has the notifyEmails property spefified. The resulting email sent to each notification email address will have variables filled into the following template:

From: Web1on1 no-reply@Web1on1.chat To: sales@acme.org

Hello,

A new Conversation Result for {form.name} is available. View the full conversation at:

https://app.web1on1.chat/conversations/590bd49f458b716046347f47#59ac405787709d4566589dd9

Thanks, {organization.displayName}

Standard Forms

The following standard set of forms and results are supported:

A full list of available fields can be seen below.

Contact Attributes

The contact attributes are fields sent with every result and not specific for the result itself. They can be set without specifying a meta.form value.

The following forms are dependent on the type of result being made:

SALES FORMS

Appointment - Showroom visit

Form ID: 64b317386170235fe4b6f240

Appointment - Test drive

Form ID: 64b317386170235fe4b6f24c

Request for Info - Find / buy car

Form ID: 64b317386170235fe4b6f26a

Request for Info - Leasing / finance

Form ID: 64b317386170235fe4b6f298

AFTERSALES FORMS

Appointment - Workshop

Form ID: 64b317386170235fe4b6f277

Appointment - Check-in

Form ID: 64400aae0760c8001d967720

Appointment - Emergency incident

Form ID: 65cb634847533a5b5820fcbc

Request for Info - Service

Form ID: 64b317386170235fe4b6f2a3

Request for Info - Parts

Form ID: 64b317386170235fe4b6f2b5

OTHER FORMS

Request for Info - Miscellaneous

Form ID: 64b317386170235fe4b6f2ac

Appointment - Rental

Form ID: 64b317386170235fe4b6f283

Share Info - Share info

Form ID: 64b317386170235fe4b6f2b1