Fields

Twitter Account objects have the following fields and links:

Fields

field name description
handle the account's username
name full name on Twitter
profile_image URL for the profile image
active whether or not the account is enabled within Desk.com
created_at when the account was created
updated_at when the account was last updated

Links

rel class embeddable? description
self twitter_account no this account
tweets tweet yes tweets for this account

List

Retrieve a paginated list of all Twitter Accounts.

GET https://yoursite.desk.com/api/v2/twitter_accounts

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

List Parameters

parameter description
username A twitter username. When provided, entries will have three additional fields: can_dm, is_following_user, and is_followed_by_user.

List Fields

For the following fields, account refers to the twitter account listed in the entry, and user refers to the twitter account specified by the username parameter.

field name description
can_dm Can the account send direct messages to the user. Can be true or false.
is_following_user Is the account following the user. Can be true or false.
is_followed_by_user Is the user following the account. Can be true or false.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/twitter_accounts \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/twitter_accounts?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/twitter_accounts?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/twitter_accounts?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "handle": "desk_dev",
        "name": "Desk.com Development",
        "profile_image": "http://www.example.com/image.png",
        "active": true,
        "created_at": "2017-01-20T23:53:30Z",
        "updated_at": "2017-02-20T23:53:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/twitter_accounts/1",
            "class": "twitter_account"
          }
        }
      },
      {
        "handle": "desk_ops",
        "name": "Desk.com Operations",
        "profile_image": "http://www.example.com/image.png",
        "active": true,
        "created_at": "2017-01-20T23:53:30Z",
        "updated_at": "2017-02-20T23:53:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/twitter_accounts/2",
            "class": "twitter_account"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single Twitter account.

GET https://yoursite.desk.com/api/v2/twitter_accounts/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "handle": "desk_dev",
  "name": "Desk.com Development",
  "profile_image": "http://www.example.com/image.png",
  "active": true,
  "created_at": "2017-01-20T23:53:30Z",
  "updated_at": "2017-02-20T23:53:30Z",
  "_links": {
    "self": {
      "href": "/api/v2/twitter_accounts/1",
      "class": "twitter_account"
    }
  }
}

Tweet Fields

Tweet objects have the following fields and links:

Fields

field name description
body the message on Twitter
direction in or out
type mention or dm
status draft, pending, sent, received, or failed
to Twitter handle which received the Tweet
from Twitter handle which sent the Tweet
twitter_status_id id of the tweet, as a string
created_at when the Tweet was created
updated_at when the Tweet was last updated

Links

rel class embeddable? description
self tweet no this Tweet
case case yes this Tweet's Case
customer customer no this Tweet's Customer
sent_by user yes the User who sent this Tweet
twitter_account twitter_account no the Twitter Account from which this Tweet was sent
favorited_by_twitter_account twitter_account no the Twitter Account from which this Tweet was favorited

List Tweets

Retrieve a paginated list of all Tweets for this Twitter Account.

GET https://yoursite.desk.com/api/v2/twitter_accounts/:id/tweets

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
4
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:id/tweets \
    -u email:password \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/tweets?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/tweets?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/tweets?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "body": "Example tweet",
        "direction": "out",
        "type": "mention",
        "status": "sent",
        "to": null,
        "from": "desk_dev",
        "tweet_status_id": "239239023",
        "created_at": "2017-07-20T17:53:30Z",
        "updated_at": "2017-07-20T17:53:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/twitter_accounts/1/tweets/1",
            "class": "tweet"
          },
          "twitter_account": {
            "href": "/api/v2/twitter_accounts/1",
            "class": "twitter_account"
          }
        }
      },
      {
        "body": "we're checking out your API examples @desk_dev",
        "direction": "out",
        "type": "mention",
        "status": "sent",
        "to": null,
        "from": "desk_dev",
        "tweet_status_id": "239239023",
        "created_at": "2017-07-20T17:53:30Z",
        "updated_at": "2017-07-20T17:53:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/twitter_accounts/1/tweets/2",
            "class": "tweet"
          },
          "twitter_account": {
            "href": "/api/v2/twitter_accounts/1",
            "class": "twitter_account"
          }
        }
      }
    ]
  }
}

Show Tweet

Retrieve a single Tweet for this Twitter Account.

GET https://yoursite.desk.com/api/v2/twitter_accounts/:twitter_account_id/tweets/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/tweets/1 \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "body": "Example tweet",
  "direction": "out",
  "type": "mention",
  "status": "sent",
  "to": null,
  "from": "desk_dev",
  "tweet_status_id": "239239023",
  "created_at": "2017-07-20T17:53:30Z",
  "updated_at": "2017-07-20T17:53:30Z",
  "_links": {
    "self": {
      "href": "/api/v2/twitter_accounts/1/tweets/1",
      "class": "tweet"
    },
    "twitter_account": {
      "href": "/api/v2/twitter_accounts/1",
      "class": "twitter_account"
    }
  }
}

Create Tweet

Post a Tweet (not associated with a case) from a Twitter Account.

POST https://yoursite.desk.com/api/v2/twitter_accounts/:id/tweets

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
body the body of the message.

Links

rel class embeddable? description
twitter_account twitter_account no the Twitter Account from which the Tweet was posted

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:id/tweets \
    -u email:password \
    -X POST \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json' \
    -d '{"body": "Example Tweet"}'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "body": "Example tweet",
  "direction": "out",
  "type": "mention",
  "status": "sent",
  "to": null,
  "from": "desk_dev",
  "tweet_status_id": "239239023",
  "created_at": "2017-07-20T17:53:30Z",
  "updated_at": "2017-07-20T17:53:30Z",
  "_links": {
    "self": {
      "href": "/api/v2/twitter_accounts/1/tweets/1",
      "class": "tweet"
    },
    "twitter_account": {
      "href": "/api/v2/twitter_accounts/1",
      "class": "twitter_account"
    }
  }
}

Show Follow

Retrieve a single user following this Twitter Account.

GET https://yoursite.desk.com/api/v2/twitter_accounts/:id/follows/:username

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Links

field name description
twitter_user twitter user link to follow for an account (optional replacement for handle param)
twitter_account twitter account link to follow from (optional)

Example Curl Request

1
2
3
4
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:id/follows/:username \
    -u email:password \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "handle": "Desk",
  "can_direct_message": true,
  "_links": {
    "self": {
      "href": "/api/v2/twitter_accounts/1/follows/Desk",
      "class": "twitter_follow"
    },
    "twitter_account": {
      "href": "/api/v2/twitter_accounts/1",
      "class": "twitter_account"
    },
    "twitter_user": {
      "href": "/api/v2/twitter_users/1",
      "class": "twitter_user"
    }
  }
}

Delete Tweet

Delete a tweet. This will erase the contents of the tweet as well as removing the tweet from Twitter.

DELETE https://yoursite.desk.com/api/v2/twitter_accounts/:twitter_account_id/tweets/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:twitter_account_id/tweets/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Create Follow

Start following a user for this Twitter Account.

POST https://yoursite.desk.com/api/v2/twitter_accounts/:id/follows

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
handle twitter handle to follow for account

Links

field name description
twitter_user twitter user link to follow for an account (optional replacement for handle param)
twitter_account twitter account link to follow from (optional)

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:id/follows \
    -u email:password \
    -X POST \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json' \
    -d '{"handle": "Desk"}'

Example Curl Request with Twitter Account

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:id/follows \
    -u email:password \
    -X POST \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json' \
    -d '{"_links": "twitter_user": { "href":"/api/v2/twitter_users/1", "class":"twitter_user" } }'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "handle": "Desk",
  "can_direct_message": true,
  "_links": {
    "self": {
      "href": "/api/v2/twitter_accounts/1/follows/Desk",
      "class": "twitter_follow"
    },
    "twitter_account": {
      "href": "/api/v2/twitter_accounts/1",
      "class": "twitter_account"
    },
    "twitter_user": {
      "href": "/api/v2/twitter_users/1",
      "class": "twitter_user"
    }
  }
}

Delete Follow

Stop following a user for this Twitter Account.

DELETE https://yoursite.desk.com/api/v2/twitter_accounts/:account_id/follows/:handle

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/1/follows/desk_ops \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Tweet Actions

Perform an action on a Tweet (such as retweeting or favoriting) from a Twitter Account.

POST https://yoursite.desk.com/api/v2/twitter_accounts/:account_id/tweets/:id/actions

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
action_type retweet to retweet a Twitter message. favorite to favorite a Twitter message. unfavorite to Un-favorite a Twitter message.

Links

rel class embeddable? description
twitter_account twitter_account no the Twitter Account on which to perform the action

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/twitter_accounts/:id/tweets/:id/actions \
    -u email:password \
    -X POST \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json' \
    -d '{"action_type": "retweet"}'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "body": "Example tweet",
  "direction": "out",
  "type": "mention",
  "status": "sent",
  "to": null,
  "from": "desk_dev",
  "tweet_status_id": "239239023",
  "created_at": "2017-07-20T17:53:30Z",
  "updated_at": "2017-07-20T17:53:30Z",
  "_links": {
    "self": {
      "href": "/api/v2/twitter_accounts/1/tweets/1",
      "class": "tweet"
    },
    "twitter_account": {
      "href": "/api/v2/twitter_accounts/1",
      "class": "twitter_account"
    }
  }
}