Sunshine Workflows Support Tasks

Important: The Sunshine Workflows API is in early access. This API is subject to change and should not be used in a production environment. Visit the Sunshine Workflows API EAP forum to provide feedback.

You can define the following Support tasks for your Sunshine Workflows:

Create a Support Ticket

Creates a ticket in Zendesk Support.

JSON Format
Name Type Required Comment
input object yes Contains fields necessary for the task. See the input object description.
key string yes A name given to the task. Note the key must be unique in the context of the entire workflow.
type string yes The type of task to execute. Must be "CREATE_SUPPORT_TICKET".
description string no A short description of your task for you and your team to reference.
optional boolean no Defaults to false. A boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution.

input object

Name Type Required Comment
ticket object yes Contains details about the ticket to create. See the ticket object description.

ticket object

Name Type Required Comment
subject string yes Subject of the ticket to be created.
description string yes Description of the ticket to be created.
requester_id integer yes* *Required if requester object is not supplied. The id of the user who is the requester of the ticket
requester object yes* *Required if requester_id is not given. See the requester object description.

See Support Ticket API for more detail.

requester object

Name Type Required Comment
name string yes Name of the ticket requester.
email string yes Email of the ticket requester.
Example

The following example task defines a task named "create_ticket" of type CREATE_SUPPORT_TICKET, which tells Sunshine Workflows what fields to expect. The description is set to "Create a support ticket for the refund request," which can aid coworkers in understanding the purpose of an existing workflow task. Finally, as discussed above, the input field has the required ticket object with subject, description, and requester. Note that the requester object can be optionally replaced with the requester_id of the requester.

{
  "key": "create_ticket",
  "type": "CREATE_SUPPORT_TICKET",
  "description": "Create a support ticket for the refund request.",
  "input": {
    "ticket": {
      "subject": "New refund requested for test user",
      "description": "hello world",
      "requester": {
        "name": "test user",
        "email": "[email protected]"
      }
    }
  }
}

Update a Support Ticket

Updates a ticket in Zendesk Support.

JSON Format
Name Type Required Comment
input object yes Contains fields necessary for the task. See the input object description.
key string yes A name given to the task. Note the key must be unique in the context of the entire workflow.
type string yes The type of task to execute. Must be "UPDATE_SUPPORT_TICKET".
description string no A short description of your task for you and your team to reference.
optional boolean no Defaults to false. A boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution.

input object

Name Type Required Comment
ticket_id string yes The id of the ticket to update.
ticket object yes Contains details about the ticket to update. See the Support Ticket API for details about supported fields.
Example

The following example task defines a task named "update_ticket" of type UPDATE_SUPPORT_TICKET, which tells Sunshine Workflows what fields to expect. The description is set to "Update a support ticket for the refund request", which can aid coworkers in understanding the purpose of an existing workflow task. The ticket_id field is set to "1", which means this task will set the status of the ticket with id = "1" to "solved".

{
  "type": "UPDATE_SUPPORT_TICKET",
  "key": "update_ticket",
  "description": "Update support ticket for the refund request.",
  "input": {
    "ticket_id": "1",
    "ticket": {
      "status": "solved"
    }
  }
}

Read a Support Ticket

Reads a ticket in Zendesk Support.

JSON Format
Name Type Required Comment
input object yes Contains fields necessary for the task. See the input object description.
key string yes A name given to the task. Note the key must be unique in the context of the entire workflow.
type string yes The type of task to execute. Must be "READ_SUPPORT_TICKET".
description string no A short description of your task for you and your team to reference.
optional boolean no Defaults to false. A boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution.

input object

Name Type Required Comment
ticket_id string no The id of the ticket to update.
Example

In the example below, a task named "read_ticket" of type READ_SUPPORT_TICKET is defined to read the ticket with id = "1".

{
  "type": "READ_SUPPORT_TICKET",
  "key": "read_ticket",
  "description": "Read support ticket for refund request.",
  "input": {
    "ticket_id": "1"
  }
}

Create a Side Conversation

Creates a side conversation in Zendesk Support.

JSON Format
Name Type Required Comment
input object yes Contains fields necessary for the task. See the input object description.
key string yes A name given to the task. Note the key must be unique in the context of the entire workflow.
type string yes The type of task to execute. Must be "CREATE_SIDE_CONVERSATION".
description string no A short description of your task for you and your team to reference.
optional boolean no Defaults to false. A boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution.

input object

Name Type Required Comment
message object yes Defines the content and the recipient of the side conversation. See the message object description.
user_id string yes The id of the user the conversation will be tied to.

message object

Name Type Required Comment
to array of objects yes Holds a list of objects representing recipients in the form of: {name: "foo", email: "[email protected]"}. For information on other supported fields, see the Side Conversation documentation.
Example

The following example demonstrates a task named "foo_create_side_conversation" of type CREATE_SIDE_CONVERSATION. The input field contains the mandatory message object, which names a single recipient by the name of "Sunshine Workflows" with the email address "[email protected]". This recipient will receive an email with the subject "foo subject" containing a body consisting of "foo body" in plain text.

{
  "type": "CREATE_SIDE_CONVERSATION",
  "key": "foo_create_side_conversation",
  "input": {
    "user_id": "67890",
    "message": {
      "to": [
        {
          "name": "Sunshine Workflows",
          "email": "[email protected]"
        }
      ],
      "format": "PLAIN",
      "via": "EMAIL",
      "subject": "foo subject",
      "body": "foo body"
    }
  }
}

The side conversation can also be directly attached to a ticket, in which case the side conversation will appear in the Zendesk UI. Provide ticket_id in the task definition as well:

{
  "type": "CREATE_SIDE_CONVERSATION",
  "key": "foo_create_side_conversation",
  "input": {
    "ticket_id": "12345",
    "user_id": "67890",
    "message": {
      "to": [
        {
          "email": "[email protected]"
        }
      ],
      "subject": "foo subject",
      "body": "foo body"
    }
  }
}

A side conversation can also create Slack notifications. In the to array, provide a user item that includes slack_workspace_id and slack_channel_id. If you need to determine your slack_workspace_id and slack_channel_id, see this stackoverflow post. Example:

{
  "type": "CREATE_SIDE_CONVERSATION",
  "key": "bar_create_side_conversation",
  "description": "Task to create a slack notification",
  "input": {
    "user_id": "445188737352",
    "message": {
      "to": [
        {
          "userId": "765419937731",
          "slack_workspace_id": "T750R288HIE",
          "slack_channel_id": "90FFS2XHHSY"
        }
      ],
      "via": "SLACK",
      "subject": "subject line",
      "body": "A slack notification sent via a symphony workflow"
    }
  }
}

Read a Side Conversation

Reads a side conversation in Zendesk Support.

JSON Format
Name Type Required Comment
input object yes Contains fields necessary for the task. See the input object description.
key string yes A name given to the task. Note the key must be unique in the context of the entire workflow.
type string yes The type of task to execute. Must be "READ_SIDE_CONVERSATION".
description string no A short description of your task for you and your team to reference.
optional boolean no Defaults to false. A boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution.

input object

Name Type Required Comment
side_conversation_id string yes The id of the side conversation to read.
ticket_id string no The id of the ticket the side conversation is associated with.
Example

Get a side conversation without a ticket_id

{
  "type": "READ_SIDE_CONVERSATION",
  "key": "foo_read_side_conversation",
  "optional": true,
  "input": {
    "side_conversation_id": "12345"
  }
}

With ticket_id:

{
  "type": "READ_SIDE_CONVERSATION",
  "key": "foo_read_side_conversation",
  "optional": true,
  "input": {
    "ticket_id": "67890",
    "side_conversation_id": "12345"
  }
}

List Side Conversations

Lists side conversations in Zendesk Support.

JSON Format
Name Type Required Comment
input object no Can optionally be included with a ticket_id to only get side conversations associated with that ticket.
key string yes A name given to the task. Note the key must be unique in the context of the entire workflow.
type string yes The type of task to execute. Must be "LIST_SIDE_CONVERSATIONS".
description string no A short description of your task for you and your team to reference.
optional boolean no Defaults to false. A boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution.

List all side conversations:

{
  "type": "LIST_SIDE_CONVERSATIONS",
  "key": "foo_list_side_conversations",
  "optional": true
}

List all side conversations associated with a specific ticket:

{
  "type": "LIST_SIDE_CONVERSATIONS",
  "key": "foo_list_side_conversations",
  "optional": true,
  "input": {
    "ticket_id": "12345"
  }
}

Update Side Conversation

Update a Side Conversation in Zendesk Support.

JSON Format
Name Type Required Comment
input object yes Contains fields necessary for the task. See the input object description.
key string yes A name given to the task. Note the key must be unique in the context of the entire workflow.
type string yes The type of task to execute. Must be "UPDATE_SIDE_CONVERSATION".
description string no A short description of your task for you and your team to reference.
optional boolean no Defaults to false. A boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution.

input object

Name Type Required Comment
side_conversation object yes Defines the content of the side conversation update. See the side_conversation object description.
user_id string yes The id of the user the conversation will be tied to.
side_conversation_id string yes The id of the side conversation that will be updated.
ticket_id string no An optional field when the side conversation is attached to a Zendesk Support ticket

side_conversation object

Name Type Comment
participants array of objects Holds a list of objects representing participants in the form of: {name: "foo", email: "[email protected]"}.
preview_text string Plain text describing the side conversation message.
state string The new state of the side conversation.
subject string The subject of the message. See the Side Conversation documentation.
Example
{
  "type": "UPDATE_SIDE_CONVERSATION",
  "key": "foo_update_side_conversation",
  "input": {
    "user_id": "67890",
    "side_conversation_id": "12345",
    "side_conversation": {
      "participants": [
        {
          "name": "Sunshine Workflows",
          "email": "[email protected]"
        }
      ],
      "state": "closed"
    }
  }
}

The side conversation you're updating may also be attached to a ticket. Provide ticket_id in the task definition as well:

{
  "type": "UPDATE_SIDE_CONVERSATION",
  "key": "foo_update_side_conversation",
  "input": {
    "user_id": "67890",
    "ticket_id": "13579",
    "side_conversation_id": "12345",
    "side_conversation": {
      "participants": [
        {
          "name": "Sunshine Workflows",
          "email": "[email protected]"
        }
      ],
      "state": "open"
    }
  }
}

Reply to Side Conversation

Replies to a side conversation in Zendesk Support.

JSON Format
Name Type Required Comment
input object yes Contains fields necessary for the task. See the input object description.
key string yes A name given to the task. Note the key must be unique in the context of the entire workflow.
type string yes The type of task to execute. Must be "REPLY_TO_SIDE_CONVERSATION".
description string no A short description of your task for you and your team to reference.
optional boolean no Defaults to false. A boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution.

input object

Name Type Required Comment
message object yes Defines the content and the recipient of the side conversation. See the message object description.
user_id string yes The id of the user the conversation will be tied to.
ticket_id string no An optional field when the side conversation is attached to a Zendesk Support ticket

message object

Name Type Required Comment
to array of objects yes Holds a list of objects representing recipients in the form of: {name: "foo", email: "[email protected]"}. For more information on other supported fields, see the Side Conversation documentation.
Example
{
  "type": "REPLY_TO_SIDE_CONVERSATION",
  "key": "foo_reply_to_side_conversation",
  "input": {
    "user_id": "67890",
    "side_conversation_id": "12345",
    "message": {
      "to": [
        {
          "name": "Sunshine Workflows",
          "email": "[email protected]"
        }
      ],
      "body": "Replying to the conversation",
      "subject": "Important update"
    }
  }
}

The side conversation you're replying to may also be attached to a ticket. Provide ticket_id in the task definition as well:

{
  "type": "REPLY_TO_SIDE_CONVERSATION",
  "key": "foo_reply_to_side_conversation",
  "input": {
    "user_id": "67890",
    "side_conversation_id": "12345",
    "ticket_id": "13790",
    "message": {
      "to": [
        {
          "name": "Sunshine Workflows",
          "email": "[email protected]"
        }
      ],
      "body": "Replying to the conversation",
      "subject": "Important update"
    }
  }
}