Skip to main content
Communication

Phone Calls

Log and manage phone interactions with automatic note creation, ticket activity tracking, and call status management.

Base URL: /api/v1/phone-calls

Auth required: Yes (auth:api) for all endpoints.

Phone calls are logged interactions. Creating a phone call may automatically:

  • Create a linked Note with a summary of the call for the contact/customer
  • Create a Ticket activity record if a ticket_id is provided

Model Properties

Property Type Required Description
id integer auto Unique identifier
user_id integer auto FK to users. Auto-assigned to the authenticated user
contact_id integer No FK to contacts. The contact involved in the call
customer_id integer No FK to customers. Auto-resolved from the contact if not provided
ticket_id integer No FK to tickets. Links this call to a support ticket
direction string Yes Call direction: inbound or outbound
status string Yes Call status (enum: phone_call_status). Values typically include completed, missed, voicemail
answered boolean No Whether the call was answered (default: true)
subject string No Call subject or topic
body text No Call notes or description
number_from string No Originating phone number
number_to string No Destination phone number
recording_file string No Path or reference to the call recording file
started_at datetime No Call start time (ISO 8601)
ended_at datetime No Call end time (ISO 8601)
transcription text No Full call transcription (AI-generated)
transcription_diarized text No Speaker-separated transcription (AI-generated)
summary text No Short call summary (AI-generated)
summary_detailed text No Detailed call summary (AI-generated)
sentiments array No Sentiment analysis results (AI-generated JSON array)
topics array No Detected topics (AI-generated JSON array)
segments array No Call segments with speaker attribution (AI-generated JSON array)
created_at datetime auto Creation timestamp
updated_at datetime auto Last update timestamp

GET /v1/phone-calls

List phone calls with filtering, sorting, and pagination.

Query parameters:

Parameter Type Description
filter[id] integer Filter by ID
filter[user_id] integer Filter by user
filter[contact_id] integer Filter by contact
filter[status] string Filter by status
filter[direction] string Filter by direction (inbound / outbound)
filter[answered] boolean Filter answered calls
filter[number_from] string Filter by origin number
filter[number_to] string Filter by destination number
filter[started_at] string Filter by start timestamp
filter[ended_at] string Filter by end timestamp
sort string Sort field
per_page integer Items per page (default 10)

Response 200: Paginated list of phone call objects.

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/phone-calls?filter[direction]=inbound&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/phone-calls",
    params={"filter[direction]": "inbound", "per_page": 25},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
calls = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->acceptJson()
    ->get('https://your-instance.bluerocktel.net/api/v1/phone-calls', [
        'filter[direction]' => 'inbound',
        'per_page' => 25,
    ]);

$calls = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/phone-calls?filter[direction]=inbound&per_page=25",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const calls = await response.json();

POST /v1/phone-calls

Log a new phone call. user_id is auto-assigned. Timestamps are parsed. Status and direction are converted to their enum values.

Body (JSON): Validated via phone_call::attributes('common', 'store'):

Field Type Required Description
contact_id integer No Linked contact
customer_id integer No Linked customer (auto-resolved from contact if not provided)
ticket_id integer No Linked ticket
status string No Call status (enum: phone_call_status)
direction string No inbound or outbound (phone_call_direction enum)
answered boolean No Whether the call was answered
number_from string No Originating number
number_to string No Destination number
started_at string No Start datetime (ISO 8601)
ended_at string No End datetime (ISO 8601)

Side effects:

  • Creates a linked Note (type: call) with a summary for the contact/customer.
  • Creates a Ticket activity record if ticket_id is provided.

Response 201: Created phone call object. Response 422: Validation error.

Examples:

curl -s -X POST "https://your-instance.bluerocktel.net/api/v1/phone-calls" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": 42,
    "direction": "outbound",
    "answered": true,
    "number_from": "+33140000000",
    "number_to": "+33155000000",
    "started_at": "2026-03-24T10:00:00Z",
    "ended_at": "2026-03-24T10:15:00Z"
  }'

import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/phone-calls",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    json={
        "contact_id": 42,
        "direction": "outbound",
        "answered": True,
        "number_from": "+33140000000",
        "number_to": "+33155000000",
        "started_at": "2026-03-24T10:00:00Z",
        "ended_at": "2026-03-24T10:15:00Z",
    },
)
call = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->acceptJson()
    ->post('https://your-instance.bluerocktel.net/api/v1/phone-calls', [
        'contact_id' => 42,
        'direction' => 'outbound',
        'answered' => true,
        'number_from' => '+33140000000',
        'number_to' => '+33155000000',
        'started_at' => '2026-03-24T10:00:00Z',
        'ended_at' => '2026-03-24T10:15:00Z',
    ]);

$call = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/phone-calls",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contact_id: 42,
      direction: "outbound",
      answered: true,
      number_from: "+33140000000",
      number_to: "+33155000000",
      started_at: "2026-03-24T10:00:00Z",
      ended_at: "2026-03-24T10:15:00Z",
    }),
  }
);
const call = await response.json();

GET /v1/phone-calls/{id}

Get a single phone call by ID.

URL parameters:

Parameter Type Description
id integer Phone call ID

Response 200: Phone call object. Response 404: Not found.

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/phone-calls/15" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/phone-calls/15",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
call = response.json()

$response = Http::withToken($token)
    ->acceptJson()
    ->get('https://your-instance.bluerocktel.net/api/v1/phone-calls/15');

$call = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/phone-calls/15",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const call = await response.json();

PUT /v1/phone-calls/{id}

Update a phone call record. Creates a ticket activity record if a ticket is linked and no activity exists yet.

URL parameters:

Parameter Type Description
id integer Phone call ID

Body (JSON): Validated via phone_call::attributes('common').

Response 201: Updated phone call object. Response 404: Not found.

Examples:

curl -s -X PUT "https://your-instance.bluerocktel.net/api/v1/phone-calls/15" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed", "ended_at": "2026-03-24T10:20:00Z"}'

import requests

response = requests.put(
    "https://your-instance.bluerocktel.net/api/v1/phone-calls/15",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    json={"status": "completed", "ended_at": "2026-03-24T10:20:00Z"},
)
call = response.json()

$response = Http::withToken($token)
    ->acceptJson()
    ->put('https://your-instance.bluerocktel.net/api/v1/phone-calls/15', [
        'status' => 'completed',
        'ended_at' => '2026-03-24T10:20:00Z',
    ]);

$call = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/phone-calls/15",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "completed",
      ended_at: "2026-03-24T10:20:00Z",
    }),
  }
);
const call = await response.json();

DELETE /v1/phone-calls/{id}

Delete a phone call record.

URL parameters:

Parameter Type Description
id integer Phone call ID

Response 200: Success message. Response 404: Not found.

Examples:

curl -s -X DELETE "https://your-instance.bluerocktel.net/api/v1/phone-calls/15" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.delete(
    "https://your-instance.bluerocktel.net/api/v1/phone-calls/15",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)

$response = Http::withToken($token)
    ->acceptJson()
    ->delete('https://your-instance.bluerocktel.net/api/v1/phone-calls/15');

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/phone-calls/15",
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
Next Incoming Mails