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. The display_to_agent is validated before creating the ticket, returning a 422 error if it is invalid.

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": "[phone]",
      "location": "Dublin, Ireland",
      "recording_url": "http://yourdomain.com/recordings/1.mp3",
      "started_at": "2019-04-16T09:14:57Z",
      "to": "[phone]",
      "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: [phone]",
    "voice_comment": {
      "from": "[phone]",
      "to": "[phone]",
      "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": "[phone]",
      "location": "Dublin, Ireland",
      "recording_url": "http://yourdomain.com/recordings/1.mp3",
      "started_at": "2019-04-16T09:14:57Z",
      "to": "[phone]",
      "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\": \"[phone]\",
      \"location\": \"Dublin, Ireland\",
      \"recording_url\": \"http://yourdomain.com/recordings/1.mp3\",
      \"started_at\": \"2019-04-16T09:14:57Z\",
      \"to\": \"[phone]\",
      \"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": "[phone]",
      "location": "Dublin, Ireland",
      "recording_url": "http://yourdomain.com/recordings/1.mp3",
      "started_at": "2019-04-16T09:14:57Z",
      "to": "[phone]",
      "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": "[phone]",
      "location": "Dublin, Ireland",
      "recording_url": "http://yourdomain.com/recordings/1.mp3",
      "started_at": "2019-04-16T09:14:57Z",
      "to": "[phone]",
      "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": "[phone]",
      "location": "Dublin, Ireland",
      "recording_url": "http://yourdomain.com/recordings/1.mp3",
      "started_at": "2019-04-16T09:14:57Z",
      "to": "[phone]",
      "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

422 Unprocessable Entity

// Status 422 Unprocessable Entity

null