Basics
Talk Partner Edition makes it easier for organizations to integrate their own call center software with Zendesk. For more information, see Understanding Talk Partner Edition .
Open Ticket in Agent's Browser
POST /api/v2/channels/voice/agents/{agent_id}/tickets/{ticket_id}/display
Allows you to instruct an agent's browser to open a ticket.
When the message is successfully delivered to an agent's browser:
Status: 200 OK
When agent_id
or ticket_id
is invalid:
Status: 404 Not Found
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
agent_id | integer | Path | true | ID of an agent |
ticket_id | integer | Path | true | The ID of the ticket |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/agents/{agent_id}/tickets/{ticket_id}/display.json \
-H "Content-Type: application/json" \
-v -u {email_address}/token:{api_token} -X POST
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/tickets/123456/display"
method := "POST"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/tickets/123456/display")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'POST',
url: 'https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/tickets/123456/display',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/tickets/123456/display"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"POST",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/tickets/123456/display")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
null
404 Not Found
// Status 404 Not Found
null
Open a User's Profile in an Agent's Browser
POST /api/v2/channels/voice/agents/{agent_id}/users/{user_id}/display
Allows you to instruct an agent's browser to open a user's profile.
When the message is successfully delivered to an agent's browser:
Status: 200 OK
When agent_id
or user_id
is invalid:
Status: 404 Not Found
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
agent_id | integer | Path | true | ID of an agent |
user_id | integer | Path | true | The id of the user |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/agents/{agent_id}/users/{user_id}/display.json \
-H "Content-Type: application/json" \
-v -u {email_address}/token:{api_token} -X POST
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/users/35436/display"
method := "POST"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/users/35436/display")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'POST',
url: 'https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/users/35436/display',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/users/35436/display"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"POST",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/channels/voice/agents/385473779372/users/35436/display")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
null
404 Not Found
// Status 404 Not Found
null
Create Ticket or Voicemail Ticket
POST /api/v2/channels/voice/tickets
Allowed For
- Agents
Creating tickets
Introduction
Creating tickets using Talk Partner Edition follows the same conventions as the Create Ticket endpoint. See Create Ticket.
Request parameters
The POST request takes a mandatory ticket
object that lists the values to set when the ticket is created.
You may also include an optional display_to_agent
value such as the ID of the agent that will see the newly created ticket.
Tickets created using this endpoint must have a via_id
parameter. See the following
section for possible values.
Zendesk Talk Integration Via IDs
Tickets created using this endpoint must have one of the following via_id
parameters:
ID | Description |
---|---|
44 | Voicemail |
45 | Phone call (inbound) |
46 | Phone call (outbound) |
Creating voicemail tickets
Request parameters
The POST request takes a mandatory ticket
object that lists the values to set when the ticket is created.
The ticket must have a voice_comment
with the following values:
Name | Type | Comment |
---|---|---|
from | string | Incoming phone number |
to | string | Dialed phone number |
recording_url | string | URL of the recording |
started_at | date | ISO 8601 timestamp of the call starting time |
call_duration | integer | Duration in seconds of the call |
answered_by_id | integer | The agent who answered the call |
transcription_text | string | Transcription of the call (optional) |
location | string | Location of the caller (optional) |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
agent_id | integer | Path | true | ID of an agent |
ticket_id | integer | Path | true | The ID of the ticket |
Example body
{
"display_to_agent": 1234,
"ticket": {
"comment": {
"body": "My printer is on fire!"
},
"priority": "urgent",
"via_id": 46,
"voice_comment": {
"answered_by_id": 28,
"call_duration": 40,
"from": "+16617480240",
"location": "Dublin, Ireland",
"recording_url": "http://yourdomain.com/recordings/1.mp3",
"started_at": "2019-04-16T09:14:57Z",
"to": "+16617480123",
"transcription_text": "The transcription of the call"
}
}
}
Code Samples
curl
Create ticket
data.json
{
"display_to_agent": 1234,
"ticket": {
"via_id": 45,
"subject": "My printer is on fire!",
"comment": { "body": "The smoke is very colorful." },
"priority": "urgent"
}
}
curl snippet
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/tickets.json \
-d @data.json \
-H "Content-Type: application/json" -v -u {email_address}/token:{api_token} -X POST
curl
Create voicemail ticket
data.json
{
"ticket": {
"via_id": 44,
"description": "Voicemail from: +16617480240",
"voice_comment": {
"from": "+16617480240",
"to": "+16617480123",
"recording_url": "http://yourdomain.com/recordings/1.mp3",
"started_at": "2019-04-16T09:14:57Z",
"call_duration": 40,
"answered_by_id": 28,
"transcription_text": "The transcription of the call",
"location": "Dublin, Ireland"
}
}
}
curl snippet
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/tickets.json \
-d @data.json \
-H "Content-Type: application/json" -v -u {email_address}/token:{api_token} -X POST
Go
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://example.zendesk.com/api/v2/channels/voice/tickets"
method := "POST"
payload := strings.NewReader(`{
"display_to_agent": 1234,
"ticket": {
"comment": {
"body": "My printer is on fire!"
},
"priority": "urgent",
"via_id": 46,
"voice_comment": {
"answered_by_id": 28,
"call_duration": 40,
"from": "+16617480240",
"location": "Dublin, Ireland",
"recording_url": "http://yourdomain.com/recordings/1.mp3",
"started_at": "2019-04-16T09:14:57Z",
"to": "+16617480123",
"transcription_text": "The transcription of the call"
}
}
}`)
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/channels/voice/tickets")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
{
\"display_to_agent\": 1234,
\"ticket\": {
\"comment\": {
\"body\": \"My printer is on fire!\"
},
\"priority\": \"urgent\",
\"via_id\": 46,
\"voice_comment\": {
\"answered_by_id\": 28,
\"call_duration\": 40,
\"from\": \"+16617480240\",
\"location\": \"Dublin, Ireland\",
\"recording_url\": \"http://yourdomain.com/recordings/1.mp3\",
\"started_at\": \"2019-04-16T09:14:57Z\",
\"to\": \"+16617480123\",
\"transcription_text\": \"The transcription of the call\"
}
}
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var data = JSON.stringify({
"display_to_agent": 1234,
"ticket": {
"comment": {
"body": "My printer is on fire!"
},
"priority": "urgent",
"via_id": 46,
"voice_comment": {
"answered_by_id": 28,
"call_duration": 40,
"from": "+16617480240",
"location": "Dublin, Ireland",
"recording_url": "http://yourdomain.com/recordings/1.mp3",
"started_at": "2019-04-16T09:14:57Z",
"to": "+16617480123",
"transcription_text": "The transcription of the call"
}
}
});
var config = {
method: 'POST',
url: 'https://example.zendesk.com/api/v2/channels/voice/tickets',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
data : data,
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
import json
from requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/channels/voice/tickets"
payload = json.loads("""{
"display_to_agent": 1234,
"ticket": {
"comment": {
"body": "My printer is on fire!"
},
"priority": "urgent",
"via_id": 46,
"voice_comment": {
"answered_by_id": 28,
"call_duration": 40,
"from": "+16617480240",
"location": "Dublin, Ireland",
"recording_url": "http://yourdomain.com/recordings/1.mp3",
"started_at": "2019-04-16T09:14:57Z",
"to": "+16617480123",
"transcription_text": "The transcription of the call"
}
}
}""")
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"POST",
url,
auth=auth,
headers=headers,
json=payload
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/channels/voice/tickets")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
"display_to_agent": 1234,
"ticket": {
"comment": {
"body": "My printer is on fire!"
},
"priority": "urgent",
"via_id": 46,
"voice_comment": {
"answered_by_id": 28,
"call_duration": 40,
"from": "+16617480240",
"location": "Dublin, Ireland",
"recording_url": "http://yourdomain.com/recordings/1.mp3",
"started_at": "2019-04-16T09:14:57Z",
"to": "+16617480123",
"transcription_text": "The transcription of the call"
}
}
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
201 Created
// Status 201 Created
{
"ticket": {
"assignee_id": 235323,
"collaborator_ids": [
35334,
234
],
"created_at": "2009-07-20T22:55:29Z",
"custom_fields": [
{
"id": 27642,
"value": "745"
},
{
"id": 27648,
"value": "yes"
}
],
"custom_status_id": 123,
"description": "The fire is very colorful.",
"due_at": null,
"external_id": "ahg35h3jh",
"follower_ids": [
35334,
234
],
"from_messaging_channel": false,
"generated_timestamp": 1304553600,
"group_id": 98738,
"has_incidents": false,
"id": 35436,
"organization_id": 509974,
"priority": "high",
"problem_id": 9873764,
"raw_subject": "{{dc.printer_on_fire}}",
"recipient": "[email protected]",
"requester_id": 20978392,
"satisfaction_rating": {
"comment": "Great support!",
"id": 1234,
"score": "good"
},
"sharing_agreement_ids": [
84432
],
"status": "open",
"subject": "Help, my printer is on fire!",
"submitter_id": 76872,
"tags": [
"enterprise",
"other_tag"
],
"type": "incident",
"updated_at": "2011-05-05T10:38:52Z",
"url": "https://company.zendesk.com/api/v2/tickets/35436.json",
"via": {
"channel": "web"
}
}
}
404 Not Found
// Status 404 Not Found
null