Skip to content
Home/
REST API Reference
/
/
Register a Fin Voice call

Register a Fin Voice call

Request

Register a Fin Voice call with Intercom. This endpoint creates an external reference that links an external call identifier to an Intercom call and conversation.

The call can be from different sources:

  • AWS Connect (default)
  • Five9
  • Zoom Phone
  • NICE CXone
  • Dialpad
  • Generic

Requires the read_conversations OAuth scope.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.17
Bodyapplication/json
phone_numberstringrequired

Phone number in E.164 format for the call

Example:"+1234567890"
call_idstringrequired

External call identifier from the call provider

Example:"call-123-abc"
sourcestring

Source of the call. Can be "five9", "zoom_phone", "nice_cxone", "dialpad", "generic", or "aws_connect". Defaults to "aws_connect", and any other value is treated as "aws_connect".

Enum:"five9""zoom_phone""nice_cxone""dialpad""generic""aws_connect"
Example:"aws_connect"
vendor_internal_idstring or null, <= 191 characters

Optional vendor-supplied identifier for linking the Fin Voice session to records in the vendor's own systems. Stored as-is and returned on every lookup. Cannot exceed 191 characters.

Example:"vendor-internal-abc-123"
dataobject or null

Additional metadata about the call

Example:
{
  "key": "value"
}
curl -i -X POST \
  https://api.intercom.io/fin_voice/register \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "phone_number": "+1234567890",
    "call_id": "call-123-abc",
    "source": "aws_connect",
    "vendor_internal_id": "vendor-internal-abc-123",
    "data": {
      "key": "value"
    }
  }'

Responses

successful

Bodyapplication/json
idinteger

The unique identifier for the external reference

Example:12345
app_idinteger

The workspace identifier

Example:12345
user_phone_numberstring

Phone number in E.164 format for the call

Example:"+1234567890"
statusstring

Status of the call. Can be "registered", "in-progress", or a resolution state

Example:"registered"
intercom_call_idstring or null

The Intercom call identifier, if the call has been matched

Example:"1234"
external_call_idstring

The external call identifier from the call provider

Example:"call-123-abc"
vendor_internal_idstring or null

Vendor-supplied identifier provided at registration time, for linking the Fin Voice session to records in the vendor's own systems. Null when the vendor did not supply one.

Example:"vendor-internal-abc-123"
intercom_conversation_idstring or null

The Intercom conversation identifier, if a conversation has been created

Example:"5678"
call_transcriptArray of objects

Array of transcript entries for the call

Example:
[]
call_summarystring

Summary of the call conversation, truncated to 256 characters. Empty string if no summary available.

Example:"Customer called about billing issue..."
intentArray of objects

Array of intent classifications for the call

Example:
[]
fin_call_durationstring or null

How long the most recent AI Agent (Fin) part of the call lasted, in seconds, returned as a string. Null until the call is matched and that part has ended, or when the call has no AI Agent part.

Example:"45"
dataobject

The metadata object supplied when the call was registered, returned verbatim. Empty object when none was supplied.

Example:
{
  "masterContactID": "abc123",
  "DNIS": "+18005551212"
}
languagestring or null

The language of the call's conversation, as a locale code. Null until the call is matched to a conversation or while no language has been set.

Example:"fr"
Response
{
  "id": 12345,
  "app_id": 12345,
  "user_phone_number": "+1234567890",
  "status": "registered",
  "intercom_call_id": null,
  "external_call_id": "call-123-abc",
  "vendor_internal_id": null,
  "intercom_conversation_id": null,
  "call_transcript": [
    {}
  ],
  "call_summary": "",
  "intent": [],
  "fin_call_duration": null,
  "data": {},
  "language": null
}