Create a call

Updated:

POST/uc/{connection_id}/call

Creates a UcCall. Provide the unified UcCall fields in the request body; they are mapped to the provider's API. Returns the created UcCall.

Parameters

fieldsstring array
Fields to return
rawstring
Raw parameters to include in the 3rd-party request. Encoded as a URL component. eg. raw parameters: foo=bar&zoo=bar -> raw=foo%3Dbar%26zoo%3Dbar
connection_idstring required
ID of the connection

Payload

idstring
Unique identifier for this call object
created_atdate-time
The date that this call object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atdate-time
The last date that this call object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
contact_idstring
The contact ID for call (reference to UcContact)
telephoneobject
The telephone number called
start_atdate-time
The start time of the call (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
end_atdate-time
The end time of the call (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
user_idstring
(reference to HrisEmployee)
contacts array
is_privateboolean
user_namestring
user_phonestring
type enum
Valid values:
"INBOUND"
"OUTBOUND"
metadata array
conversation_identifierstring
opaque identifier shared across legs of one interaction
status enum
Valid values:
"QUEUED"
"RINGING"
"IN_PROGRESS"
"COMPLETED"
"BUSY"
The current or final status of the call
answer_atdate-time
When the call was answered (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
duration_secondsnumber
Call length in seconds
cost_amountnumber
What the integration charged for the call
currencystring
ISO 4217 currency of cost_amount
parent_idstring
The parent call (leg) that this call belongs to
instructions array
Write-only: what the call does once answered (create/update only; never returned)

Returns

Response fieldTypeRequiredDescription
idstringNoUnique identifier for this call object
created_atstring (date-time)NoThe date that this call object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)NoThe last date that this call object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
contact_idstringNoThe contact ID for call (reference to UcContact)
telephoneobjectNoThe telephone number called
telephone.telephonestringNo
telephone.typeenumNoValues: WORK, HOME, OTHER, FAX, MOBILE
start_atstring (date-time)NoThe start time of the call (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
end_atstring (date-time)NoThe end time of the call (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
user_idstringNo(reference to HrisEmployee)
contactsUcContact[]No
contacts[].idstringNoUnique identifier for this contact object
contacts[].created_atstring (date-time)NoThe date that this contact object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
contacts[].updated_atstring (date-time)NoThe last date that this contact object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
contacts[].namestringNoThe name of the contact
contacts[].first_namestringNo
contacts[].last_namestringNo
contacts[].titlestringNoThe job title of the contact
contacts[].companystringNoThe company/organization name of the contact
contacts[].emailsUcEmail[]NoAn array of email addresses for this contact
contacts[].emails[].emailstringYes
contacts[].emails[].typeenumNoValues: WORK, HOME, OTHER
contacts[].telephonesUcTelephone[]NoAn array of telephones for this contact
contacts[].telephones[].telephonestringYes
contacts[].telephones[].typeenumNoValues: WORK, HOME, OTHER, FAX, MOBILE
contacts[].metadataUcMetadata[]No
contacts[].metadata[].idstringNo
contacts[].metadata[].slugstringNo
contacts[].metadata[].valueobjectNo
contacts[].metadata[].namespacestringNo
contacts[].metadata[].formatenumNoValues: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
contacts[].metadata[].extra_dataobjectNo
is_privatebooleanNo
user_namestringNo
user_phonestringNo
typeenumNoValues: INBOUND, OUTBOUND
metadataUcMetadata[]No
metadata[].idstringNo
metadata[].slugstringNo
metadata[].valueobjectNo
metadata[].namespacestringNo
metadata[].formatenumNoValues: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
metadata[].extra_dataobjectNo
conversation_identifierstringNoopaque identifier shared across legs of one interaction
statusenumNoThe current or final status of the call Values: QUEUED, RINGING, IN_PROGRESS, COMPLETED, BUSY, NO_ANSWER, FAILED, CANCELED, OTHER
answer_atstring (date-time)NoWhen the call was answered (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
duration_secondsnumberNoCall length in seconds
cost_amountnumberNoWhat the integration charged for the call
currencystringNoISO 4217 currency of cost_amount
parent_idstringNoThe parent call (leg) that this call belongs to
instructionsUcCallInstruction[]NoWrite-only: what the call does once answered (create/update only; never returned)
instructions[].typeenumYesValues: SAY, PLAY, PAUSE, DIAL, HANGUP
instructions[].textstringNoSAY: text to speak
instructions[].languagestringNoSAY: BCP 47 language code (e.g. en-US), passed through as-is (Bandwidth maps it to its nearest locale)
instructions[].audio_urlstringNoPLAY: public MP3 or WAV URL
instructions[].secondsnumberNoPAUSE: length of silence
instructions[].telephoneUcCallInstruction_telephoneNoDIAL: number to dial and bridge
instructions[].telephone.telephonestringYes
instructions[].telephone.typeenumNoValues: WORK, HOME, OTHER, FAX, MOBILE
instructions[].sip_uristringNoDIAL: SIP address to dial instead of telephone
instructions[].user_phonestringNoDIAL: caller ID on the dialed leg (defaults to the call's user_phone)
instructions[].timeout_secondsnumberNoDIAL: how long to ring before giving up

Errors

Errors return the HTTP status code and a JSON body with statusCode, error (the short label) and message (a human-readable detail).

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests to unified.to API; max requests per minute: N"
}
StatusErrorMeaning
400Bad RequestThe request was malformed or failed validation.
401UnauthorizedThe connection is likely broken; re-authorize it.
403ForbiddenThe connection is missing permissions or scopes.
404Not FoundThe requested resource does not exist.
429Too Many RequestsRate limit exceeded (see the two sources below).
500Internal Server ErrorAn unexpected error occurred.
501Not ImplementedNot supported by this integration.

Errors from the underlying integration pass through: the integration's status comes back as ours (429, 401, 403, 404 or 5xx), usually with its message. When the integration's error body is unclear, Unified extracts what it can and returns a clearer message.

429 Too Many Requests

A 429 has two possible sources:

  • The integration's own rate limit, passed through.
  • Unified's workspace limit: a rolling 60 seconds, set by plan, with the message Too many requests to unified.to API; max requests per minute: N.
const options = {
  method: 'POST',
  url: 'https://api.unified.to/uc/5de520f96e439b002043d8dc/call',
  headers: {
    authorization: 'bearer .....'
  },
  data: undefined,
  params: {
    fields: '',
    raw: '',
  }
};

const results = await axios.request(options);
Are we missing anything? Let us know
Was this page helpful?