Difference between revisions of "Setting"

From docs
Jump to: navigation, search
(Created page with "## API Name Get Settings Details ## Base URL `https://apimobile.callproof.com` ## Endpoint `/api/settings` ## Purpose Returns the signed-in user’s combined app configurat...")
 
(→‎Successful Response (200))
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
## API Name
+
== [[Mobile_API]] »Get Settings ==
−
Get Settings Details
 
  
−
## Base URL
+
=== Base URL ===
−
`https://apimobile.callproof.com`
+
https://apimobile.callproof.com
  
−
## Endpoint
+
=== Endpoint ===
−
`/api/settings`
+
/api/settings
  
−
## Purpose
+
=== Purpose ===
−
Returns the signed-in user’s combined app configuration in one call: user preferences and capability flags, company-level feature toggles, dashboard widget layout, onboarding tooltip state, and the AI voice agent identifiers used by the app.
+
Retrieves a combined settings payload for the authenticated user and company, including user settings, company settings, dashboard widgets, tooltip flags, and AI agent configuration.
  
−
## HTTP Method
+
=== HTTP Method ===
−
`GET`
+
GET
  
−
## Headers
+
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Authorization || Yes || Bearer access token
 +
|}
  
−
| Header | Required | Description |
+
=== Security ===
−
|--------|----------|-------------|
+
* '''Yes''' – Requires Bearer Token authentication.
−
| Authorization | Yes | `Bearer {access_token}` |
 
−
| Accept | No | `application/json` |
 
  
−
## Security
+
=== Parameters ===
−
Requires a valid Bearer token. Token expiry and disabled-account checks apply.
 
  
−
## Parameters
+
==== Path Parameters ====
−
No path, query, or body parameters. Settings are resolved from the authenticated user and their company.
+
None.
  
−
---
+
==== Query Parameters ====
 +
None.
  
−
## Successful Response (200)
+
==== Request Body ====
 +
None.
  
−
Envelope:
+
=== cURL Example for Android ===
  
−
| Field | Type | Description |
+
<pre> curl --location 'https://apimobile.callproof.com/api/settings' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' </pre>
−
|-------|------|-------------|
 
−
| clientStatusCode | integer | `200` on success |
 
−
| user_id | integer | Authenticated user ID |
 
−
| company_id | integer | User’s company ID |
 
−
| data | object | Combined settings payload (below) |
 
−
| uri | string | Request URL |
 
  
−
### `data` top-level keys
+
=== cURL Example for iOS ===
  
−
| Field | Type | Description |
+
<pre> curl --location 'https://apimobile.callproof.com/api/settings' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' </pre>
−
|-------|------|-------------|
 
−
| user_settings | object | User/company preference and feature flags |
 
−
| company_settings | object | Company widget / follow-up feature flags |
 
−
| widgets | object | Dashboard widget flags and ordering (omitted if widget order is unavailable for the user) |
 
−
| tooltip | object | Per-screen tooltip / onboarding flags |
 
−
| agents | object or string | AI agent `id` + `name` when available; otherwise empty string |
 
  
−
### `data.user_settings`
+
=== Successful Response (200) ===
 +
Returns the combined settings payload.
  
−
| Field | Type | Description |
+
{| class="wikitable"
−
|-------|------|-------------|
+
! Field !! Type !! Description
−
| manager | integer | `1` if user is a manager, else `0` |
+
|-
−
| market_manager | integer | `1` if user is a market manager, else `0` |
+
| clientStatusCode || integer || Status indicator for the client (for example, 200)
−
| first_name | string | User first name |
+
|-
−
| last_name | string | User last name |
+
| user_id || integer || Identifier of the authenticated user
−
| gps | integer | GPS setting value (`0` if unset) |
+
|-
−
| is_sync_gps | integer | Whether GPS sync is enabled |
+
| company_id || integer || Identifier of the authenticated user’s company
−
| sync_calls | integer | Call sync interval in seconds (default `3600`) |
+
|-
−
| sync_gps | integer | GPS sync interval in seconds (default `900`) |
+
| data || object || Settings payload (see below)
−
| people | integer | `1` if company People tab is enabled, else `0` |
+
|-
−
| event_form | integer | Default event form ID for the user (`0` if none) |
+
| uri || string || Requested resource URI
−
| is_hide_mobile_appt_popup | integer | Hide mobile appointment popup (`1`/`0`) |
+
|}
−
| is_start_appointment | integer | Start-appointment feature (`1`/`0`) |
 
−
| is_contact_page_as_homepage | integer | Contacts as homepage (`1`/`0`) |
 
−
| is_logs_enabled | integer | Company logs feature (`1`/`0`) |
 
−
| is_automatic_logs_enabled | integer | Automatic logs (`1`/`0`) |
 
−
| event_form_id | integer | Stored event form ID (`0` if unset) |
 
−
| is_delete_personnel | integer | Allow deleting personnel (`1`/`0`) |
 
−
| is_twilio_enabled | integer | Company Twilio (`1`/`0`) |
 
−
| is_videomessage_enabled | integer | Company video messages (`1`/`0`) |
 
−
| is_unread_videomessage | mixed | Unread video-message indicator for the user |
 
−
| display_glass_usa_dashboard_btn | boolean | Show Glass USA dashboard button when company is configured for it |
 
−
| omega_key | string | Decrypted Omega key when Glass USA is configured; otherwise `""` |
 
−
| primary_location_search_type | integer/boolean | Company’s primary location search type ID (`false` only if company record missing) |
 
−
| background_image | string | Full URL to company background thumbnail, or `""` |
 
−
| logo | string | Full URL to company logo thumbnail, or `""` |
 
−
| user_image | string | Full URL to user (or title) image thumbnail, or `""` |
 
−
| isShowTaskPopup | boolean/integer | Whether the task popup should be shown |
 
−
| introductory_video | string | Introductory tutorial video link, or `""` |
 
−
| new_videos_count | integer | Count of new tutorial videos |
 
−
| is_2fa_enabled | boolean | `true` if user or company has 2FA enabled |
 
−
| hide_my_events | mixed | Hide-my-events preference |
 
−
| is_business_card_widget_enabled | mixed | Company business-card widget flag |
 
−
| is_ai_enabled | mixed | Company-level AI enabled flag |
 
−
| chat_bot | integer | User chatbot setting (`0` if AI off / unset) |
 
−
| ai_call_summary | integer | User AI call-summary setting (`0` if AI off / unset) |
 
−
| ai_prompt_edit | integer | User AI prompt-edit setting (`0` if AI off / unset) |
 
−
| ai_virtual_assistant | integer | User virtual-assistant setting (present when company AI is enabled) |
 
  
−
> Note: `google_place_search_latitude` / `google_place_search_longitude` exist in the settings builder only when latitude/longitude are passed into that builder. This route does not pass them, so those fields are not included here.
+
==== data ====
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| user_settings || object || User/company preference and feature flags for the mobile app
 +
|-
 +
| company_settings || object || Company-level widget/feature flags
 +
|-
 +
| widgets || object || Dashboard widget configuration
 +
|-
 +
| tooltip || object || Tooltip enablement flags by screen
 +
|-
 +
| agents || object/string || AI agent config (<code>id</code>, <code>name</code>), or empty when unavailable
 +
|}
  
−
### `data.company_settings`
+
==== data.user_settings ====
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| manager || integer || Manager flag (1/0)
 +
|-
 +
| market_manager || integer || Market manager flag (1/0)
 +
|-
 +
| first_name || string || User first name
 +
|-
 +
| last_name || string || User last name
 +
|-
 +
| gps || integer || GPS setting value
 +
|-
 +
| is_sync_gps || integer || Whether GPS sync is enabled
 +
|-
 +
| sync_calls || integer || Call sync interval (seconds; default 3600 when unset)
 +
|-
 +
| sync_gps || integer || GPS sync interval (seconds; default 900 when unset)
 +
|-
 +
| people || integer || People-tab enabled flag (1/0)
 +
|-
 +
| event_form || integer || After-call event form ID (0 when none)
 +
|-
 +
| is_hide_mobile_appt_popup || integer || Hide mobile appointment popup flag
 +
|-
 +
| is_start_appointment || integer || Start appointment enabled flag
 +
|-
 +
| is_contact_page_as_homepage || integer || Contact page as homepage flag
 +
|-
 +
| is_logs_enabled || integer || Company logs enabled flag
 +
|-
 +
| is_automatic_logs_enabled || integer || Automatic logs enabled flag
 +
|-
 +
| event_form_id || integer || User-linked event form ID
 +
|-
 +
| is_delete_personnel || integer || Allow delete personnel flag
 +
|-
 +
| is_twilio_enabled || integer || Twilio enabled flag
 +
|-
 +
| is_videomessage_enabled || integer || Video message enabled flag
 +
|-
 +
| is_unread_videomessage || integer/boolean || Unread video message indicator
 +
|-
 +
| display_glass_usa_dashboard_btn || boolean || Whether Glass USA dashboard button is shown
 +
|-
 +
| omega_key || string || External key when Glass USA is configured
 +
|-
 +
| primary_location_search_type || integer/boolean || Primary location search type setting
 +
|-
 +
| background_image || string || Company background image URL
 +
|-
 +
| user_image || string || User profile image URL
 +
|-
 +
| logo || string || Company logo URL
 +
|-
 +
| isShowTaskPopup || boolean || Whether the task popup should be shown
 +
|-
 +
| introductory_video || string || Introductory video link
 +
|-
 +
| new_videos_count || integer || Count of new tutorial videos for the current day
 +
|-
 +
| is_2fa_enabled || boolean || Whether two-factor authentication is enabled for user or company
 +
|-
 +
| hide_my_events || boolean || Hide my events preference
 +
|-
 +
| is_business_card_widget_enabled || boolean || Business card widget enabled
 +
|-
 +
| is_ai_enabled || boolean/integer || Company AI enabled flag
 +
|-
 +
| chat_bot || integer || Chat bot enabled flag
 +
|-
 +
| ai_call_summary || integer || AI call summary enabled flag
 +
|-
 +
| ai_prompt_edit || integer || AI prompt edit enabled flag
 +
|-
 +
| ai_virtual_assistant || integer || AI virtual assistant enabled flag (when AI is enabled)
 +
|}
  
−
| Field | Type | Description |
+
==== data.company_settings ====
−
|-------|------|-------------|
+
{| class="wikitable"
−
| is_recommended_followup_enabled | mixed | Recommended follow-up feature at company level |
+
! Field !! Type !! Description
−
| is_task_widget_enabled | mixed | Task widget feature at company level |
+
|-
−
| is_opportunity_widget_enabled | mixed | Opportunity widget feature at company level |
+
| is_recommended_followup_enabled || boolean || Recommended follow-up feature enabled
 +
|-
 +
| is_task_widget_enabled || boolean || Task widget enabled
 +
|-
 +
| is_opportunity_widget_enabled || boolean || Opportunity widget enabled
 +
|}
  
−
### `data.widgets` (when present)
+
==== data.widgets ====
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| recommended_followup || integer || Recommended follow-up widget status
 +
|-
 +
| task_widget || integer || Task widget status
 +
|-
 +
| widgets || array || Active/ordered widgets
 +
|-
 +
| widgets_available || array || Inactive/available widgets
 +
|}
  
−
| Field | Type | Description |
+
==== data.tooltip ====
−
|-------|------|-------------|
+
{| class="wikitable"
−
| recommended_followup | integer/mixed | Recommended-followup widget status (`0` if unavailable) |
+
! Field !! Type !! Description
−
| task_widget | integer/mixed | Task widget status (`0` if unavailable) |
+
|-
−
| widgets | array | Active / ordered widgets for the user |
+
| has_tooltip_enable || boolean || Master tooltip enable flag
−
| widgets_available | array | Inactive / available widgets for the user |
+
|-
 +
| home_screen || boolean || Home screen tooltip
 +
|-
 +
| accounts_screen || boolean || Accounts screen tooltip
 +
|-
 +
| route_screen || boolean || Route screen tooltip
 +
|-
 +
| places_screen || boolean || Places screen tooltip
 +
|-
 +
| places_filter_screen || boolean || Places filter screen tooltip
 +
|-
 +
| home_settings_screen || boolean || Home settings screen tooltip
 +
|}
  
−
### `data.tooltip`
+
==== data.agents ====
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| id || string/integer || Agent identifier
 +
|-
 +
| name || string || Agent display name
 +
|}
  
−
| Field | Type | Description |
+
=== Error Responses ===
−
|-------|------|-------------|
+
{| class="wikitable"
−
| has_tooltip_enable | boolean/mixed | Master tooltip flag |
+
! Status Code !! Meaning
−
| home_screen | boolean/mixed | Home screen tooltip |
+
|-
−
| accounts_screen | boolean/mixed | Accounts screen tooltip |
+
| 400 || Bad Request – settings could not be retrieved
−
| route_screen | boolean/mixed | Routes screen tooltip |
+
|-
−
| places_screen | boolean/mixed | Places screen tooltip |
+
| 401 || Unauthorized – missing, invalid, or expired Bearer token
−
| places_filter_screen | boolean/mixed | Places filter tooltip |
+
|}
−
| home_settings_screen | boolean/mixed | Home settings tooltip |
 
  
−
If no tooltip record exists, all of the above default to `false`.
+
* '''400''' – An error occurred while loading settings.
−
 
+
* '''401''' – Authentication failed or the access token is missing/expired.
−
### `data.agents` (when resolved)
 
−
 
 
−
| Field | Type | Description |
 
−
|-------|------|-------------|
 
−
| id | string | ElevenLabs agent ID (live vs test depends on environment URL) |
 
−
| name | string | Agent display name |
 
−
 
 
−
### Example (shape)
 
−
 
 
−
```json
 
−
{
 
−
  "clientStatusCode": 200,
 
−
  "user_id": 12345,
 
−
  "company_id": 678,
 
−
  "data": {
 
−
    "user_settings": {
 
−
      "manager": 0,
 
−
      "market_manager": 0,
 
−
      "first_name": "Jane",
 
−
      "last_name": "Doe",
 
−
      "gps": 1,
 
−
      "is_sync_gps": 1,
 
−
      "sync_calls": 3600,
 
−
      "sync_gps": 900,
 
−
      "people": 1,
 
−
      "event_form": 12,
 
−
      "is_hide_mobile_appt_popup": 0,
 
−
      "is_start_appointment": 1,
 
−
      "is_contact_page_as_homepage": 0,
 
−
      "is_logs_enabled": 1,
 
−
      "is_automatic_logs_enabled": 0,
 
−
      "event_form_id": 12,
 
−
      "is_delete_personnel": 0,
 
−
      "is_twilio_enabled": 1,
 
−
      "is_videomessage_enabled": 0,
 
−
      "is_unread_videomessage": 0,
 
−
      "display_glass_usa_dashboard_btn": false,
 
−
      "omega_key": "",
 
−
      "primary_location_search_type": 1,
 
−
      "background_image": "https://apimobile.callproof.com/...",
 
−
      "logo": "https://apimobile.callproof.com/...",
 
−
      "user_image": "https://apimobile.callproof.com/...",
 
−
      "isShowTaskPopup": false,
 
−
      "introductory_video": "https://...",
 
−
      "new_videos_count": 0,
 
−
      "is_2fa_enabled": false,
 
−
      "hide_my_events": false,
 
−
      "is_business_card_widget_enabled": true,
 
−
      "is_ai_enabled": true,
 
−
      "chat_bot": 1,
 
−
      "ai_call_summary": 1,
 
−
      "ai_prompt_edit": 0,
 
−
      "ai_virtual_assistant": 1
 
−
    },
 
−
    "company_settings": {
 
−
      "is_recommended_followup_enabled": true,
 
−
      "is_task_widget_enabled": true,
 
−
      "is_opportunity_widget_enabled": true
 
−
    },
 
−
    "widgets": {
 
−
      "recommended_followup": 1,
 
−
      "task_widget": 1,
 
−
      "widgets": [],
 
−
      "widgets_available": []
 
−
    },
 
−
    "tooltip": {
 
−
      "has_tooltip_enable": false,
 
−
      "home_screen": false,
 
−
      "accounts_screen": false,
 
−
      "route_screen": false,
 
−
      "places_screen": false,
 
−
      "places_filter_screen": false,
 
−
      "home_settings_screen": false
 
−
    },
 
−
    "agents": {
 
−
      "id": "...",
 
−
      "name": "..."
 
−
    }
 
−
  },
 
−
  "uri": "https://apimobile.callproof.com/api/settings"
 
−
}
 
−
```
 
−
 
 
−
---
 
−
 
 
−
## Error Responses
 
−
 
 
−
### Failure while loading settings
 
−
HTTP response body uses the standard error envelope with `clientStatusCode` **400** and an `error.message` from the failure.
 
−
 
 
−
| Field | Type | Description |
 
−
|-------|------|-------------|
 
−
| clientStatusCode | integer | `400` |
 
−
| error.code | integer | Default unauthorized/error code used by the API error helper |
 
−
| error.message | string | Exception / failure message |
 
−
| uri | string | Request URL |
 
−
 
 
−
```json
 
−
{
 
−
  "clientStatusCode": 400,
 
−
  "error": {
 
−
    "code": 401,
 
−
    "message": "..."
 
−
  },
 
−
  "uri": "https://apimobile.callproof.com/api/settings"
 
−
}
 
−
```
 
−
 
 
−
### Auth / account failures
 
−
Handled by middleware before the handler runs (invalid/expired token, disabled account). Those return the platform’s usual unauthorized responses rather than the settings payload.
 
−
 
 
−
---
 
−
 
 
−
Next in `routes/api.php` after this is **`GET /api/app-settings`**. Say if you want that documented next.
 

Latest revision as of 12:26, 20 July 2026

Mobile_API »Get Settings

Base URL

https://apimobile.callproof.com

Endpoint

/api/settings

Purpose

Retrieves a combined settings payload for the authenticated user and company, including user settings, company settings, dashboard widgets, tooltip flags, and AI agent configuration.

HTTP Method

GET

Headers

Header Required Description
Authorization Yes Bearer access token

Security

  • Yes – Requires Bearer Token authentication.

Parameters

Path Parameters

None.

Query Parameters

None.

Request Body

None.

cURL Example for Android

 curl --location 'https://apimobile.callproof.com/api/settings' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

cURL Example for iOS

 curl --location 'https://apimobile.callproof.com/api/settings' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Successful Response (200)

Returns the combined settings payload.

Field Type Description
clientStatusCode integer Status indicator for the client (for example, 200)
user_id integer Identifier of the authenticated user
company_id integer Identifier of the authenticated user’s company
data object Settings payload (see below)
uri string Requested resource URI

data

Field Type Description
user_settings object User/company preference and feature flags for the mobile app
company_settings object Company-level widget/feature flags
widgets object Dashboard widget configuration
tooltip object Tooltip enablement flags by screen
agents object/string AI agent config (id, name), or empty when unavailable

data.user_settings

Field Type Description
manager integer Manager flag (1/0)
market_manager integer Market manager flag (1/0)
first_name string User first name
last_name string User last name
gps integer GPS setting value
is_sync_gps integer Whether GPS sync is enabled
sync_calls integer Call sync interval (seconds; default 3600 when unset)
sync_gps integer GPS sync interval (seconds; default 900 when unset)
people integer People-tab enabled flag (1/0)
event_form integer After-call event form ID (0 when none)
is_hide_mobile_appt_popup integer Hide mobile appointment popup flag
is_start_appointment integer Start appointment enabled flag
is_contact_page_as_homepage integer Contact page as homepage flag
is_logs_enabled integer Company logs enabled flag
is_automatic_logs_enabled integer Automatic logs enabled flag
event_form_id integer User-linked event form ID
is_delete_personnel integer Allow delete personnel flag
is_twilio_enabled integer Twilio enabled flag
is_videomessage_enabled integer Video message enabled flag
is_unread_videomessage integer/boolean Unread video message indicator
display_glass_usa_dashboard_btn boolean Whether Glass USA dashboard button is shown
omega_key string External key when Glass USA is configured
primary_location_search_type integer/boolean Primary location search type setting
background_image string Company background image URL
user_image string User profile image URL
logo string Company logo URL
isShowTaskPopup boolean Whether the task popup should be shown
introductory_video string Introductory video link
new_videos_count integer Count of new tutorial videos for the current day
is_2fa_enabled boolean Whether two-factor authentication is enabled for user or company
hide_my_events boolean Hide my events preference
is_business_card_widget_enabled boolean Business card widget enabled
is_ai_enabled boolean/integer Company AI enabled flag
chat_bot integer Chat bot enabled flag
ai_call_summary integer AI call summary enabled flag
ai_prompt_edit integer AI prompt edit enabled flag
ai_virtual_assistant integer AI virtual assistant enabled flag (when AI is enabled)

data.company_settings

Field Type Description
is_recommended_followup_enabled boolean Recommended follow-up feature enabled
is_task_widget_enabled boolean Task widget enabled
is_opportunity_widget_enabled boolean Opportunity widget enabled

data.widgets

Field Type Description
recommended_followup integer Recommended follow-up widget status
task_widget integer Task widget status
widgets array Active/ordered widgets
widgets_available array Inactive/available widgets

data.tooltip

Field Type Description
has_tooltip_enable boolean Master tooltip enable flag
home_screen boolean Home screen tooltip
accounts_screen boolean Accounts screen tooltip
route_screen boolean Route screen tooltip
places_screen boolean Places screen tooltip
places_filter_screen boolean Places filter screen tooltip
home_settings_screen boolean Home settings screen tooltip

data.agents

Field Type Description
id string/integer Agent identifier
name string Agent display name

Error Responses

Status Code Meaning
400 Bad Request – settings could not be retrieved
401 Unauthorized – missing, invalid, or expired Bearer token
  • 400 – An error occurred while loading settings.
  • 401 – Authentication failed or the access token is missing/expired.
Retrieved from "http://docs.callproof.com/index.php?title=Setting&oldid=2557"