# REST Resource: projects.calls

## Resource: Call

The Call resource. This represents a call, such as an SMS.

<div class="highlight"><span class="filename">JSON representation</span><pre><code><span class="p">{</span>
  <span class="s2">&quot;name&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;to&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;from&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;fromLocation&quot;</span><span class="p">: </span><span class="p">{</span>
    <span class="kd">object (</span><a href="#numberlocation"><strong><span class="kd">NumberLocation</span></strong></a><span class="kd">)</span>
  <span class="p">}</span><span class="p">,</span>
  <span class="s2">&quot;fromZone&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;isPrivate&quot;</span><span class="p">: </span><span class="kd">boolean</span><span class="p">,</span>
  <span class="s2">&quot;labels&quot;</span><span class="p">: </span><span class="p">{</span>
    <span class="kd">string</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
    <span class="p">...</span>
  <span class="p">}</span><span class="p">,</span>
  <span class="s2">&quot;transport&quot;</span><span class="p">: </span><span class="kd">enum (</span><a href="#calltransport"><strong><span class="kd">Transport</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;direction&quot;</span><span class="p">: </span><span class="kd">enum (</span><a href="#calldirection"><strong><span class="kd">Direction</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;errorCode&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;errorMessage&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;price&quot;</span><span class="p">: </span><span class="p">{</span>
    <span class="kd">object (</span><a href="https://github.com/googleapis/googleapis/blob/master/google/type/money.proto" target="_blank"><strong><span class="kd">google.type.Money</span></strong></a><span class="kd">)</span>
  <span class="p">}</span><span class="p">,</span>
  <span class="s2">&quot;state&quot;</span><span class="p">: </span><span class="kd">enum (</span><a href="#callstate"><strong><span class="kd">State</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;createTime&quot;</span><span class="p">: </span><span class="kd">string (</span><a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank"><strong><span class="kd">Timestamp</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;startTime&quot;</span><span class="p">: </span><span class="kd">string (</span><a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank"><strong><span class="kd">Timestamp</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;ringTime&quot;</span><span class="p">: </span><span class="kd">string (</span><a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank"><strong><span class="kd">Timestamp</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;answerTime&quot;</span><span class="p">: </span><span class="kd">string (</span><a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank"><strong><span class="kd">Timestamp</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;endTime&quot;</span><span class="p">: </span><span class="kd">string (</span><a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank"><strong><span class="kd">Timestamp</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;bridged&quot;</span><span class="p">: </span><span class="kd">boolean</span><span class="p">,</span>
  <span class="s2">&quot;originatingCall&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;createMethod&quot;</span><span class="p">: </span><span class="kd">enum (</span><a href="#callcreatemethod"><strong><span class="kd">CreateMethod</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;options&quot;</span><span class="p">: </span><span class="p">{</span>
    <span class="kd">object (</span><a href="#callapicalloptions"><strong><span class="kd">ApiCallOptions</span></strong></a><span class="kd">)</span>
  <span class="p">}</span><span class="p">,</span>
  <span class="s2">&quot;sipCallId&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;answerDuration&quot;</span><span class="p">: </span><span class="kd">string (</span><a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank"><strong><span class="kd">Duration</span></strong></a><span class="kd">)</span>
<span class="p">}</span></code></pre></div>

Fields | &nbsp;
--|--
<span class="e-code">name</span> | <span class="e-code">string</span><br/>Resource name of the call. It is of the form `projects/*/calls/*`
<span class="e-code">to</span> | <span class="e-code">string</span><br/>Required. The recipient of the call.<br/><br/>For PSTN calls, this is the phone number in +E164 format.<br/><br/>For calls to a SIP domain, this is the URI in the To header, in the format `sip:user-or-number@domain`.<br/><br/>When placing outgoing API calls, only PSTN is supported. 
<span class="e-code">from</span> | <span class="e-code">string</span><br/>Required. The originator of the call.<br/><br/>For PSTN calls, this is the CLI (Caller ID) in +E164 format. When placing outgoing API calls, this is required.<br/><br/>For calls to a SIP domain, this is the URI in the From header, in the format `sip:user-or-number@domain`.<br/><br/>This field will not be set if the CLI originated from the PSTN and `is_private` is true. 
<span class="e-code">fromLocation</span> | <span class="e-code">object ([NumberLocation](#numberlocation))</span><br/>The approximate location where the call originated from. Only set for INCOMING calls (this may be changed in the future). 
<span class="e-code">fromZone</span> | <span class="e-code">string</span><br/>The zone associated with the `from` phone number, if applicable. Only applicable for PSTN. Only set for INCOMING calls (this may be changed in the future). 
<span class="e-code">isPrivate</span> | <span class="e-code">boolean</span><br/>Whether the Caller ID is private.
<span class="e-code">labels</span> | <span class="e-code">map (key: <span class="e-code">string</span>, value: <span class="e-code">string</span>)</span><br/>You can store any arbitrary data against labels. The maximum number of keys is 50. The maximum length of all keys and values combined is 10kB.
<span class="e-code">transport</span> | <span class="e-code">enum ([Transport](#calltransport))</span><br/>Output only. The transport that carried this call.
<span class="e-code">direction</span> | <span class="e-code">enum ([Direction](#calldirection))</span><br/>Output only. The direction of the call. Can be `outgoing` for calls that are sent or `incoming` for calls that are received.
<span class="e-code">errorCode</span> | <span class="e-code">string</span><br/>Output only. If the outgoing call failed to be delivered, the reason why.
<span class="e-code">errorMessage</span> | <span class="e-code">string</span><br/>Output only. The human readable call associated with the error.
<span class="e-code">price</span> | <span class="e-code">object (<a href="https://github.com/googleapis/googleapis/blob/master/google/type/money.proto" target="_blank">google.type.Money</a> format)</span><br/>Output only. The price of this call. This may be set at various times. Generally, it is available when the call reaches a terminal state, either immediately or shortly afterwards.<br/><br/>This price is the price of the call itself, and does not include charges from the consumption of other paid services, such as text-to-speech and transcription.
<span class="e-code">state</span> | <span class="e-code">enum ([State](#callstate))</span><br/>Output only. The current state of the call.
<span class="e-code">createTime</span> | <span class="e-code">string (<a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank">Timestamp</a> format)</span><br/>Output only. The creation time of the call. Output only.
<span class="e-code">startTime</span> | <span class="e-code">string (<a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank">Timestamp</a> format)</span><br/>Output only. The time the call was started. For an incoming call, this is the same as `create_time`. For an outgoing call, this is the time that the call attempt commenced.
<span class="e-code">ringTime</span> | <span class="e-code">string (<a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank">Timestamp</a> format)</span><br/>Output only. The time the call started ringing. Only set for outgoing call.
<span class="e-code">answerTime</span> | <span class="e-code">string (<a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank">Timestamp</a> format)</span><br/>Output only. The time the call was answered.
<span class="e-code">endTime</span> | <span class="e-code">string (<a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank">Timestamp</a> format)</span><br/>Output only. The time the call finished.
<span class="e-code">bridged</span> | <span class="e-code">boolean</span><br/>Output only. Was the call bridged with another call at any point?
<span class="e-code">originatingCall</span> | <span class="e-code">string</span><br/>Output only. The name of the call that originated this call, set for outgoing calls that were created during the execution of another call, of the form `projects/*/calls/*`.
<span class="e-code">createMethod</span> | <span class="e-code">enum ([CreateMethod](#callcreatemethod))</span><br/>Output only. How this call started.
<span class="e-code">options</span> | <span class="e-code">object ([ApiCallOptions](#callapicalloptions))</span><br/>Required. The options to use to handle this call. This is only required when a call is created using the API.
<span class="e-code">sipCallId</span> | <span class="e-code">string</span><br/>Output only. The `Call-ID` header of the call. Only set when transport is SIP.
<span class="e-code">answerDuration</span> | <span class="e-code">string (<a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank">Duration</a> format)</span><br/>Output only. The duration for which the call was answered. If the call was not answered or it has not reached a terminal state, this field will not be set.

## NumberLocation

Location information for a phone number.

<div class="highlight"><span class="filename">JSON representation</span><pre><code><span class="p">{</span>
  <span class="s2">&quot;regionCode&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;administrativeArea&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;locality&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;coordinates&quot;</span><span class="p">: </span><span class="p">{</span>
    <span class="kd">object (</span><a href="https://github.com/googleapis/googleapis/blob/master/google/type/latlng.proto" target="_blank"><strong><span class="kd">google.type.LatLng</span></strong></a><span class="kd">)</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

Fields | &nbsp;
--|--
<span class="e-code">regionCode</span> | <span class="e-code">string</span><br/>CLDR region code of the country/region. See http://cldr.unicode.org/ and http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html for details. Example: "AU" for Australia.
<span class="e-code">administrativeArea</span> | <span class="e-code">string</span><br/>If known, the highest administrative subdivision of a country or region. For example, this can be a state, a territory, a province, an oblast, or a prefecture.
<span class="e-code">locality</span> | <span class="e-code">string</span><br/>If known, the locality associated with the phone number. Generally refers to the city/town portion of the address. Examples: AU suburb, US city, IT comune, UK post town.
<span class="e-code">coordinates</span> | <span class="e-code">object (<a href="https://github.com/googleapis/googleapis/blob/master/google/type/latlng.proto" target="_blank">google.type.LatLng</a> format)</span><br/>If known, the approximate coordinates of the location.

## Call.Transport

The transport of a call.

Enums | &nbsp;
--|--
<span class="e-code">TRANSPORT_UNSPECIFIED</span> | Unspecified transport.
<span class="e-code">PSTN</span> | The call was transported over PSTN (Public Switched Telephone Network).
<span class="e-code">CLIENT</span> | The call was transported over an Enfonica Client (WebRTC).
<span class="e-code">SIP</span> | The call was transported over SIP.

## Call.Direction

The direction of a call.

Enums | &nbsp;
--|--
<span class="e-code">DIRECTION_UNSPECIFIED</span> | Unspecified direction.
<span class="e-code">OUTGOING</span> | An outgoing call.
<span class="e-code">INCOMING</span> | An incoming call

## Call.State

The state of a call.

Enums | &nbsp;
--|--
<span class="e-code">STATE_UNSPECIFIED</span> | Unspecified status.
<span class="e-code">QUEUED</span> | The call has been queued.
<span class="e-code">STARTING</span> | The call is being attempted.
<span class="e-code">RINGING</span> | The remote party is ringing.
<span class="e-code">IN_PROGRESS</span> | The call has been answered.
<span class="e-code">COMPLETED</span> | The call was answered and is now finished.
<span class="e-code">FAILED</span> | The call could not be made.
<span class="e-code">NOT_ANSWERED</span> | The call was not answered. This is the same as the call waiting to be answered and timing out.
<span class="e-code">BUSY</span> | The remote party indicated they were busy.
<span class="e-code">REJECTED</span> | The call was not answered and it was actively rejected.

## Call.CreateMethod

How a call was created.

Enums | &nbsp;
--|--
<span class="e-code">CREATE_METHOD_UNSPECIFIED</span> | Unspecified create method.
<span class="e-code">INCOMING_CALL</span> | The call was created as a result of receiving an incoming call.
<span class="e-code">PARENT_CALL</span> | The call was created by its parent call, e.g. VoiceML `<Call>` or `<Redirect>`.
<span class="e-code">API</span> | The call was creating using the API.

## Call.ApiCallOptions

Options that are applied to the call when it is an outgoing call created by the API.

<div class="highlight"><span class="filename">JSON representation</span><pre><code><span class="p">{</span>
  <span class="s2">&quot;handlerUris&quot;</span><span class="p">: </span><span class="p">[</span>
    <span class="kd">string</span>
  <span class="p">]</span><span class="p">,</span>
  <span class="s2">&quot;stateUpdateUri&quot;</span><span class="p">: </span><span class="kd">string</span><span class="p">,</span>
  <span class="s2">&quot;timeoutSeconds&quot;</span><span class="p">: </span><span class="kd">number (</span><a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank"><strong><span class="kd">int32</span></strong></a><span class="kd">)</span><span class="p">,</span>
  <span class="s2">&quot;recording&quot;</span><span class="p">: </span><span class="p">{</span>
    <span class="kd">object (</span><a href="/docs/cloud-voice/api-reference/rest/v1beta1/CallRecordingConfig/"><strong><span class="kd">CallRecordingConfig</span></strong></a><span class="kd">)</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

Fields | &nbsp;
--|--
<span class="e-code">handlerUris[]</span> | <span class="e-code">string</span><br/>Required. One or more URIs where VoiceML requests should be made to control the call. The first URI will be attempted first, while the other URIs are only used if the initial URI fails. Can be any supported URI. Minimum 1 URI, maximum 5 URIs.
<span class="e-code">stateUpdateUri</span> | <span class="e-code">string</span><br/>The URL where state updates should be sent.
<span class="e-code">timeoutSeconds</span> | <span class="e-code">number (<a href="https://developers.google.com/protocol-buffers/docs/proto3#json" target="_blank">int32</a> format)</span><br/>The maximum amount of time, in seconds, the call is allowed to attempt an endpoint. Default 30 seconds. Minimum 1, maximum 600 seconds. 
<span class="e-code">recording</span> | <span class="e-code">object ([CallRecordingConfig](/docs/cloud-voice/api-reference/rest/v1beta1/CallRecordingConfig/))</span><br/>The configuration of call recording. If not specified, no call recording will be configured.

## Methods

Methods | &nbsp;
--|--
<span class="e-code">[create](/docs/cloud-voice/api-reference/rest/v1beta1/projects.calls/create/)</span> | <span class="e-code">POST /v1beta1/{parent}/calls</span><br/>Creates a call in the state QUEUED. This will cause an outgoing call to be started.<br/><br/>The caller must have `voice.calls.create` permission on the project.
<span class="e-code">[get](/docs/cloud-voice/api-reference/rest/v1beta1/projects.calls/get/)</span> | <span class="e-code">GET /v1beta1/{name}</span><br/>Retrieves a Call identified by the supplied resource name.<br/><br/>The caller must have `voice.calls.get` permission on the project.
<span class="e-code">[list](/docs/cloud-voice/api-reference/rest/v1beta1/projects.calls/list/)</span> | <span class="e-code">GET /v1beta1/{parent}/calls</span><br/>Lists the Calls of the specified project. List returns Calls sorted by create_time descending.<br/><br/>The caller must have `voice.calls.list` permission on the project.

