Partner API V3

The Partner API is designed to seamlessly integrate with your existing user management system and/or payment gateway, enabling the synchronization of user accounts and the creation of authentication tokens or email invitations. This integration facilitates the use of the Talkio solution alongside your services.

This documentation comes with a Postman collection for registered users. If you aren't familiar with Postman read more here.

Authentication Requirements

For security purposes, each API request must include two headers: x-api-key and x-provider. These credentials, essential for authenticating your requests, will be provided by your designated Talkio contact.

Warning: Keep your API key and provider ID confidential to prevent unauthorized access. Do not expose these credentials in client-side code.

Two User Management Options

When integrating with the Partner API, you have two options for user management:

1. Handle user authentication in your application.
2. Use the authentication solution on Talkio/Talkio White Label.

Option 1: Handle User Authentication in Your Application. This option is suitable if you already have an online course or system where users are logged in. You can obtain a token from the API and redirect users to Talkio without requiring them to log in again.

Option 2: Use Talkio's Authentication Solution. This option is suitable if you do not have an authentication system set up. You can trigger an email invitation on signup/payment, which will be sent to the end user. This email will include a temporary password allowing them to log in via the Talkio login form.

In both options, you will need to delete users to ensure that expired users no longer have access. Our billing is based on usage, so maintaining accuracy is crucial.

API Endpoints

All endpoints below use the v3 base path:

/api/partner/v3/organizations/{organization-slug}

Authentication is handled with the standard partner headers:

• x-provider
• x-api-key

User Management

Create User

POST /api/partner/v3/organizations/{organization-slug}/users

Creates a member or facilitator in the organization.

Request Body

• id (required): Your external user identifier
• userName (required)
• userType (required): member or facilitator
• email (optional)
• phoneNumber (optional)
• accountExpiresAt (optional)
• productId (optional)

Example Request Body:

{
  "id": "user-1",
  "userName": "User 1",
  "userType": "member",
  "email": "user-1@example.com",
  "phoneNumber": "+14155550123",
  "accountExpiresAt": "2027-02-22T19:35:25.000Z",
  "productId": "school-plan"
}

Invite User

POST /api/partner/v3/organizations/{organization-slug}/users/invite

Creates an email invitation for a user who should join the organization.

Request Body

• email (required)
• accountExpiresAt (optional)

Example Request Body:

{
  "email": "user-1@example.com",
  "accountExpiresAt": "2027-02-22T19:35:25.000Z"
}

Retrieve User

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}

Fetches one active user. The {user-id} value can be the partner user id and, for this endpoint, email lookups are also supported.

Retrieve All Users

GET /api/partner/v3/organizations/{organization-slug}/users?page={page}&limit={limit}&userType={userType}

Fetches active users in the organization.

Query Parameters

• page (optional): Default 1
• limit (optional): Default 10, minimum 10, maximum 100
• userType (optional): member or facilitator

Update User

PUT /api/partner/v3/organizations/{organization-slug}/users/{user-id}

Updates an active user. Partial updates are supported.

Request Body

• userName (optional)
• email (optional)
• phoneNumber (optional)
• accountExpiresAt (optional)
• productId (optional)

Delete User

DELETE /api/partner/v3/organizations/{organization-slug}/users/{user-id}

Deletes an active user from the organization. This endpoint also supports deleting suspended users that appear in the expired-users endpoints.

User Authentication Token

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/token

Returns a login token, expiry timestamp, and direct login link for an active user.

User Settings

Retrieve User Settings

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/settings

Returns the current user settings payload.

Update User Settings

PUT /api/partner/v3/organizations/{organization-slug}/users/{user-id}/settings

Updates user settings. Partial updates are supported.

Supported Fields

• practiceLanguage
• userLanguage
• uiLanguage
• practiceLanguageProficiency
• readAloudSpeed
• defaultTutor
• showChatTranslations
• showChatRomanization
• showLiveFeedback
• hideIntroFlow

Example Request Body:

{
  "userLanguage": "en-US",
  "practiceLanguage": "en-GB",
  "uiLanguage": "en-US",
  "practiceLanguageProficiency": "elementary",
  "readAloudSpeed": 3,
  "showChatTranslations": true,
  "showChatRomanization": true,
  "showLiveFeedback": true,
  "defaultTutor": "Emma",
  "hideIntroFlow": false
}

Expired Users

Retrieve Expired Users

GET /api/partner/v3/organizations/{organization-slug}/expired-users?page={page}&limit={limit}

Fetches suspended / expired users for the organization.

The expired-user response includes:

• expiredAt
• memberType

Retrieve Expired User

GET /api/partner/v3/organizations/{organization-slug}/expired-users/{user-id}

Fetches one expired user. The {user-id} value can be the partner user id or the user's email.

Usage And Reporting

Daily User Stats

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/usage/stats?date=YYYY-MM-DD&timezone=America/New_York

Returns daily usage statistics for one user. This endpoint supports both active and expired users. Conversation stats include wordsPerMinute in the conversations.user and videoConversations.user objects.

Query Parameters

• date (required): format YYYY-MM-DD
• timezone (optional): IANA timezone such as America/New_York

Monthly User Stats

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/usage/monthly-stats?month=YYYY-MM&language=en-US&timezone=America/New_York

Returns monthly usage statistics for one user. This endpoint supports both active and expired users. Monthly conversation stats include wordsPerMinute in the conversations.user and videoConversations.user objects.

Query Parameters

• month (required): format YYYY-MM
• language (optional): return stats for a specific practice language only
• timezone (optional): IANA timezone such as America/New_York

Weekly Assessment

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/weekly-assessment/{target-week}

Fetches a weekly language assessment for the requested week.

Path Parameters

• target-week (required): a date within the target week in YYYY-MM-DD format

Query Parameters

• practiceLanguage (optional)

Conversations

Retrieve Conversations

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/conversations?page={page}&limit={limit}&promptTemplateId={promptTemplateId}

Fetches conversations for an active user.

Query Parameters

• page (optional): Default 1
• limit (optional): Default 10, minimum 10, maximum 100
• promptTemplateId (optional): prompt template slug

Retrieve Conversation

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/conversations/{conversation-id}

Fetches one conversation with its messages and metadata.

Organization Preference

Retrieve Organization Preference

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/organization-preference

Returns the user's preferred organization slug for the same partner, or null if no preference is set.

Update Organization Preference

PUT /api/partner/v3/organizations/{organization-slug}/users/{user-id}/organization-preference

Sets the user's preferred organization.

Request Body

{
  "organizationSlug": "partner-example-school"
}

The target organization must belong to the same partner, and the user must already belong to that organization.

Legacy Usage Endpoints

The following endpoints remain supported for backwards compatibility, but new integrations should use Daily User Stats and Monthly User Stats instead.

Usage (Deprecated)

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/{target-month}

Returns legacy monthly usage totals.

Usage Duration (Deprecated)

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/usage/duration?month=YYYY-MM

Returns legacy monthly usage-duration totals by feature.

Token Authentication (User Management Option 1)

Generate an authentication token for a user, allowing them to log in.

The response will include a token used for authentication.

GET /api/partner/v3/organizations/{organization-slug}/users/{user-id}/token

User Authentication Process

Once a token is acquired, users can be logged in using the following URL structure:

https://[SUBDOMAIN].[DOMAIN].com/authentication/partner/?path=[OPTIONAL_PATH]&token=[TOKEN]

Important: Tokens have a limited validity period. Generate the login link close to the user's intended login time to prevent token expiration.

The path parameter can redirect users to specific app sections post-login, defaulting to the dashboard.

Logout Mechanism

Users remain authenticated for 30 days post-login unless they manually log out or clear their cookies. In such events, users will be redirected to a logout page. By default, this page is set to your organization's domain, but a custom logout URL can be provided to redirect users elsewhere, such as the initial access point for Talkio services. Please contact us if you wish to provide another logout URL.

Embedding in an Iframe

You can configure the solution to run inside an iframe. To do this, you must obtain an authentication token from the API and include it in the iframe URL. Additionally, you can specify an optional path for redirection after authentication.

Example

<iframe
  src="https://subdomain.yourdomain.com/authentication/partner/?token=[AUTHENTICATION_TOKEN]&path=[OPTIONAL_PATH]"
  width="100%"
  height="100%"
  style="border: none"
  allow="microphone; screen-wake-lock"
  allow="same-origin"
></iframe>

Security & Authentication

For security reasons, the parent domain hosting the iframe must be the same as the iframe's child domain, though subdomains can differ. This is due to the browser's security policies regarding iframes and the use of cookies for authentication.

Example

Host Website: https://my-company.com

Talkio White Label: https://app.my-company.com

Specifying a Path

To navigate to specific sections of the web app after login, use the path parameter in the iframe URL. This allows direct linking to various parts of the app or specific content. For example, to link directly to the "Books & Literature" template:

<iframe
  src="https://subdomain.yourdomain.com/authentication/partner/?token=[AUTHENTICATION_TOKEN]&path=app/chat?t=books-literature"
  width="100%"
  height="100%"
  style="border: none"
  allow="microphone"
  allow="same-origin"
></iframe>

Note: The &path= parameter has been updated to specify the target content.

UI

When the app is embedded correctly in an iframe, the default UI elements (like the logo and navigation) are automatically hidden. This allows you to design and integrate your own custom UI as needed. The app's responsive design ensures it can be embedded in various formats, such as a sidebar or any other layout that suits your requirements.

Furthermore, to hide the sidebar on chat pages, append the following to the iframe URL: &hide-chat-sidebar=true. However, keep in mind that this will limit functionality, as the information contained in the sidebar will not be accessible elsewhere.

Custom Domain Configuration

For your Talkio white label solution, we can set up a custom domain on a subdomain in the following form: [subdomain].[domain].[tld]. Please reach out to us at developer@talkio.ai to get the DNS records for your solution.