Set a call's outcome

Set a call’s post-call outcome: what happened, a number for it, and data to attach.

Send only the fields to change: null clears one, and custom_metadata replaces the whole object. A new custom_outcome joins the agent’s list of post-call outcomes, which the web app’s analytics and filters use. Answers with the updated call. The same calls can be updated as read with GET /v1/calls/{id}. To find a call by the customer’s number, list the agent’s calls with customer_phone_number and limit=1: the newest call comes first.

PATCH

calls

{id}

Set a call's outcome

curl --request PATCH \
  --url https://api.us.phonely.ai/v1/calls/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "custom_metadata": {},
  "custom_outcome": "<string>",
  "custom_outcome_value": 123
}
'

import requests

url = "https://api.us.phonely.ai/v1/calls/{id}"

payload = {
    "custom_metadata": {},
    "custom_outcome": "<string>",
    "custom_outcome_value": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({custom_metadata: {}, custom_outcome: '<string>', custom_outcome_value: 123})
};

fetch('https://api.us.phonely.ai/v1/calls/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.us.phonely.ai/v1/calls/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'custom_metadata' => [
        
    ],
    'custom_outcome' => '<string>',
    'custom_outcome_value' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.us.phonely.ai/v1/calls/{id}"

	payload := strings.NewReader("{\n  \"custom_metadata\": {},\n  \"custom_outcome\": \"<string>\",\n  \"custom_outcome_value\": 123\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.us.phonely.ai/v1/calls/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"custom_metadata\": {},\n  \"custom_outcome\": \"<string>\",\n  \"custom_outcome_value\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.us.phonely.ai/v1/calls/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"custom_metadata\": {},\n  \"custom_outcome\": \"<string>\",\n  \"custom_outcome_value\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "action_items": [
    "<string>"
  ],
  "agent_id": "<string>",
  "business_phone_number": "<string>",
  "campaign_id": "<string>",
  "custom_metadata": {},
  "custom_outcome": "<string>",
  "custom_outcome_value": 123,
  "customer_name": "<string>",
  "customer_phone_number": "<string>",
  "duration_seconds": 123,
  "ended_at": "2023-11-07T05:31:56Z",
  "ended_reason": "<string>",
  "follow_up_reason": "<string>",
  "id": "<string>",
  "is_follow_up_needed": true,
  "key_points": [
    "<string>"
  ],
  "long_summary": "<string>",
  "mentioned_date": "2023-12-25",
  "mentioned_email": "<string>",
  "mentioned_time": "<string>",
  "object": "call",
  "outcome": "<string>",
  "purpose": "<string>",
  "sentiment": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "status": "<string>",
  "summary": "<string>",
  "type": "<string>",
  "unanswered_questions": [
    "<string>"
  ],
  "warm_transfer_started_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

An org API key: Authorization: Bearer phk_…

Headers

Phonely-Organization

string | null

Optional. Must be the key's org.

Path Parameters

string

required

The call's ID.

Body

application/json

The post-call outcome to set. Send only the fields to change; null clears one.

custom_metadata

Custom Metadata · object | null

Any JSON object to attach to the call, up to 32 KB. It replaces the whole object stored before. An object the call can't store, such as one nested more than 20 levels deep or with a list directly inside a list, is a 400.

custom_outcome

string | null

The outcome, in your own words, such as Booked. 1 to 255 characters. It's added to the agent's list of post-call outcomes.

Required string length: 1 - 255

custom_outcome_value

number | null

A number to go with the outcome, such as a deal value.

Response

Successful Response

One call with its call analysis. The transcript and recording have their own endpoints.

action_items

string[] | null

required

Action items the conversation left for the customer.

agent_id

string

required

The agent that handled the call.

business_phone_number

string | null

required

The Phonely number on the call, as recorded: usually E.164, such as +14155550100.

campaign_id

string | null

required

The outbound campaign that placed the call, if any.

custom_metadata

Custom Metadata · object | null

required

Data your integration attached to the call, as sent. null when none.

custom_outcome

string | null

required

The post-call outcome your integration set, such as Booked. null when none.

custom_outcome_value

number | null

required

A number your integration set with the outcome, such as a deal value. null when none.

customer_name

string | null

required

The name the customer gave. null when they gave none.

customer_phone_number

string | null

required

The customer on the call, as recorded: usually E.164, but Anonymous or a SIP address when they withheld their number. null for web calls.

duration_seconds

number | null

required

How long the call lasted. null when not recorded, as for a call that never connected.

ended_at

string<date-time> | null

required

When the call ended. null while it is still in progress.

ended_reason

string | null

required

Why the call ended. null when it was not recorded. Known values: assistant_ended_call, assistant_forwarded_call, customer_ended_call, hangup_during_warm_transfer, max_duration_reached, silence_timeout, no_answer, user_busy, call_failed, voicemail, no_one_engaged, pre_screen_hangup, greeting_hangup, pre_greeting_hangup, greeting_timeout, pre_call_rejected, pipeline_error, unknown_error, unsure. More can be added, so handle values you don't recognize.

follow_up_reason

string | null

required

Why a person should follow up, and who.

string

required

The call's ID.

is_follow_up_needed

boolean | null

required

Whether a person should follow up with the customer.

key_points

string[] | null

required

Key points from the conversation.

long_summary

string | null

required

A longer summary from call analysis, up to six sentences.

mentioned_date

string<date> | null

required

A date mentioned on the call, such as an appointment.

mentioned_email

string | null

required

An email address mentioned on the call.

mentioned_time

string | null

required

A time mentioned on the call, as HH:mm (24-hour).

object

string

default:call

required

The type of this object, always call.

Allowed value: "call"

outcome

string | null

required

The call's outcome, as the agent's call analysis labels it.

purpose

string | null

required

The call's purpose, in a few words.

sentiment

string | null

required

The customer's sentiment: from call analysis, unless someone changed it in the web app. Known values: positive, negative, neutral, unsure. More can be added, so handle values you don't recognize.

started_at

string<date-time> | null

required

When the call started, or was queued if it never connected.

status

string

required

Where the call is in its lifecycle. Known values: completed, ended, in_progress, in_warm_transfer, queued, queueing, redial_scheduled, cancelled, dnc, failed, transferred_sold, transferred_not_sold, transferred_pending_sale, rev_share_pending_qualification, transferred_busy, transferred_no_answer, transferred_failed. More can be added, so handle values you don't recognize.

summary

string | null

required

A short summary from call analysis.

type

string | null

required

How the call happened. Known values: inbound_phone_call, outbound_phone_call, warm_transfer, web_call, web_chat, messaging_session, call_and_messaging, pay_per_call, unknown. More can be added, so handle values you don't recognize.

unanswered_questions

string[] | null

required

Questions the agent didn't answer.

warm_transfer_started_at

string<date-time> | null

required

When a warm transfer to a person began. null when there was none.

⌘I

Set a call's outcome

curl --request PATCH \
  --url https://api.us.phonely.ai/v1/calls/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "custom_metadata": {},
  "custom_outcome": "<string>",
  "custom_outcome_value": 123
}
'

import requests

url = "https://api.us.phonely.ai/v1/calls/{id}"

payload = {
    "custom_metadata": {},
    "custom_outcome": "<string>",
    "custom_outcome_value": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({custom_metadata: {}, custom_outcome: '<string>', custom_outcome_value: 123})
};

fetch('https://api.us.phonely.ai/v1/calls/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.us.phonely.ai/v1/calls/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'custom_metadata' => [
        
    ],
    'custom_outcome' => '<string>',
    'custom_outcome_value' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.us.phonely.ai/v1/calls/{id}"

	payload := strings.NewReader("{\n  \"custom_metadata\": {},\n  \"custom_outcome\": \"<string>\",\n  \"custom_outcome_value\": 123\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.us.phonely.ai/v1/calls/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"custom_metadata\": {},\n  \"custom_outcome\": \"<string>\",\n  \"custom_outcome_value\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.us.phonely.ai/v1/calls/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"custom_metadata\": {},\n  \"custom_outcome\": \"<string>\",\n  \"custom_outcome_value\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "action_items": [
    "<string>"
  ],
  "agent_id": "<string>",
  "business_phone_number": "<string>",
  "campaign_id": "<string>",
  "custom_metadata": {},
  "custom_outcome": "<string>",
  "custom_outcome_value": 123,
  "customer_name": "<string>",
  "customer_phone_number": "<string>",
  "duration_seconds": 123,
  "ended_at": "2023-11-07T05:31:56Z",
  "ended_reason": "<string>",
  "follow_up_reason": "<string>",
  "id": "<string>",
  "is_follow_up_needed": true,
  "key_points": [
    "<string>"
  ],
  "long_summary": "<string>",
  "mentioned_date": "2023-12-25",
  "mentioned_email": "<string>",
  "mentioned_time": "<string>",
  "object": "call",
  "outcome": "<string>",
  "purpose": "<string>",
  "sentiment": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "status": "<string>",
  "summary": "<string>",
  "type": "<string>",
  "unanswered_questions": [
    "<string>"
  ],
  "warm_transfer_started_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

API v1

API v1 endpoints

Legacy API

Web SDK

Set a call's outcome

Authorizations

Headers

Path Parameters

Body

Response