smalltalk API docs

Introduction

Talks

Recordings

Groups

Webhooks

Welcome to the smalltalk API!

This is a RESTful API that allows you to create and manage talks.

To get started, you'll need to create a partner account by signing up for smalltalk and creating a partner account.
Once you've created an account, you can find your API token in the settings for your organization.

Create a talk

Make a talk for your org via the api. name is required.

POST /api/p/talk

Name	Description
name (required)	The name of your talk
room_type	What will the talk room be used for? Options: `default` \| `questions` \| `hosted_events` Default: `default`
access	Access level for the talk. Options:`anyone` \| `invite_only` Default: `anyone`
theme_id	optional ID of a theme to apply. Manage themes in the theme editor.
mic_behavior	Non-host mic setting Options: `start_off` \| `start_on` Default: `start_on`
start_time	Optional start time (ISO format date-time)
end_time	Optional end time (ISO format date-time)
description	Optional description text to show on the page before participants join a room
subscriptions_allowed	Optional boolean for whether or not users are allowed to subscribe to a talk

# NB: to attach an optional theme_id, find the id in the theme editor
    curl -X "POST" "https://www.atsmalltalk.com/api/p/talk" \
    -H 'Content-Type: application/json; charset=utf-8' \
    -H 'Authorization: Bearer your_api_token_here' \
    -d $'{
    "name": "My Talk",
    "room_type": "hosted_events",
    "access": "anyone",
    "mic_behavior": "start_off",
    "start_time": "",
    "theme_id": "690c6c3c-db13-4b97-aad9-51aab24a23d8"
    }'

Sample response:

{
      "talk": {
      "id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      "created_at": "2021-12-16T06:06:25.244015+00:00",
      "updated_at": "2021-12-16T06:06:25.244015+00:00",
      "name": "My Talk",
      "thumbnail_url": null,
      "created_by_id": "5b274af8-42ec-4870-acdd-02n02gslx0g",
      "partner_id": "<partner_id>",
      "price": null,
      "currency": null,
      "start_time": "2021-12-16T06:06:07.628+00:00",
      "short_url": "https://atslt.com/abcdefgh",
      "schedule": null,
      "access": "anyone",
      "mic_behavior": "start_off"
    },
    "error": null
    }

Get talks

Get talks or 1 talk by ID. talk_id is optional.

GET /api/v1/partners/talks

Name	Description
talk_id	The ID of a talk

curl -G “https://www.atsmalltalk.com/api/v1/partners/talks”                 -H 'Content-Type: application/json; charset=utf-8' 
-H 'Authorization: Bearer <YOUR TOKEN HERE>’ 
-d ‘talk_id=<TALK ID>’ (optional)

Sample response:

{
    "talks”: [{
      "id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      "created_at": "2021-12-16T06:06:25.244015+00:00",
      "updated_at": "2021-12-16T06:06:25.244015+00:00",
      "name": "My Talk",
      "thumbnail_url": null,
      "created_by_id": "5b274af8-42ec-4870-acdd-02n02gslx0g",
      "partner_id": "dbdc83b7-fd4a-45d8-ac3c-4ff55732b5c8",
      "price": null,
      "currency": null,
      "start_time": "2021-12-16T06:06:07.628+00:00",
      "schedule": null,
      "access": "anyone",
      "mic_behavior": "start_off"
    }],
    "error": null
    }

Create a join link

Optionally, use the API to create unique join links by talk ID.

display_name and display_img are optional and uid are unique across your users.
POST /api/p/talk/join

Name	Description
talk_id (required)	The ID of the smalltalk to join
uid	Optional string ID from your system for this particular user. If you leave this blank, you will get a generic un-authenticated link to the talk (this is useful to give to the talk host, who will be logged in already as an org admin).
display_name	Optional name to display for the user joining via this link. Ignored if uid is blank.
display_img	Optional url to a photo to display for the user joining via this link. Ignored if uid is blank.
role	Optional role to have this user added to your org. Can be either `admin` \| `member` \| `none`.

curl -X "POST" "https://www.atsmalltalk.com/api/p/talk/join" \
    -H 'Content-Type: application/json; charset=utf-8' \
    -H 'Authorization: Bearer <your_api_token>' \
    -d $'{
    "talk_id": "<talk_id>",
    "uid": "1234",
    "display_name": "Fran Ismali (@fran-ismali)",
    "display_img": "https://example.com/img.png"
    }'

Sample response:

{
      "url":"https://atslt.com/abcdefg"
    }

Get recordings for talks or 1 talk

talk_id is optional.

GET /api/v1/partners/recordings

Name	Description
talk_id	The id of a talk

curl -G "https://www.atsmalltalk.com/api/v1/partners/recordings"                 -H 'Content-Type: application/json; charset=utf-8' 
-H 'Authorization: Bearer [YOUR TOKEN HERE]’ 
-d ‘talk_id=[YOUR TALK ID]’ (optional param)

Sample response:

{
    “recordings”: [{
      "id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      "created_at": "2021-12-16T06:06:25.244015+00:00",
      “start”_time: "2021-12-16T06:06:25.244015+00:00",
      “file_name: “12345678.mp4”,
      “share_permission: “private”,
      "created_by_id": "5b274af8-42ec-4870-acdd-02n02gslx0g",
      “user”_id: "<user_id>”,
      “transcription”: {(…transcription data}},
      }],
    "error": null
}

Create a group of talks

Make a group for your org via the api. name is required.

POST /api/v1/partners/groups

Name	Description
name (required)	The name of the group
description	description of the group.
rank	the order in which the group should appear in the organization's list of groups
visible	whether or not the group should be visible to users

curl -X “POST” "https://www.atsmalltalk.com/api/v1/partners/groups”                 -H 'Content-Type: application/json; charset=utf-8' 
-H 'Authorization: Bearer [YOUR TOKEN HERE]’' 
-d $'{
  "id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
    "name": "Smalltalk Community",
    "description”: “join us!”,
    "rank": 4,
    "visible”: true
}

Sample response:

{
    [{
      "id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      "name": "Smalltalk Community",
      "description": “join us!”,
      "rank": 4,
      "visible": true,
      "currency": null,
      "price": null,
      "partner_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j"
    }],
    “error”: null
}

Get an organization's groups

GET /api/v1/partners/groups

curl -G "https://www.atsmalltalk.com/api/v1/partners/groups” 
-H 'Content-Type: application/json; charset=utf-8' 
-H 'Authorization: Bearer [YOUR TOKEN HERE]'

Sample response:

{
    groups: [{
      "id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      "name": "Smalltalk Community",
      "description": “join us!”,
      "rank": 4,
      "visible": true,
      "currency": null,
      "price": null,
      "partner_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j"
    }],
    “error”: null
}

Add/remove talks in a group

PUT /api/v1/partners/group_talks

Name	Description
group_id (required)	The id of the group
talk_ids (required)	array of talk ids to be in the group.

curl -X “PUT” "https://www.atsmalltalk.com/api/v1/partners/group_talks" 
-H 'Content-Type: application/json; charset=utf-8' 
-H 'Authorization: Bearer [YOUR TOKEN HERE]' 
-d "group_id=df6829ae-35bf-42ls-851e-sdfoijg82224j" (required)
-d “talk_ids=[df6829ae-35bf-42ls-851e-sdfoijg82224j, df6829ae-35bf-42ls-851e-sdfoijg82224j]” (required)

Sample response:

{
  “talk_groups”: [
    {
      “talk_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      “partner_id: "df6829ae-35bf-42ls-851e-sdfoijg82224j",
    },
    {
      “talk_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
        “partner_id: "df6829ae-35bf-42ls-851e-sdfoijg82224j",
    }
    ],    
    "error": null
}

Get one of your organization's groups

GET /api/v1/partners/group_talks

Name	Description
group_id (required)	The id of the group

   curl -G "https://www.atsmalltalk.com/api/v1/partners/group_talks" 
-H 'Content-Type: application/json; charset=utf-8' 
-H 'Authorization: Bearer [YOUR TOKEN HERE]' 
-d "group_id=df6829ae-35bf-42ls-851e-sdfoijg82224j" (required)

Sample response:

{
    "group": {
      "id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      "name": "Smalltalk Lunch 'n Learns",
      "description": "Weekly lunch and learns taking place",
      "rank": 2.00000000000001,
      "visible": true,
      "currency": null,
      "price": null,
      "partner_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j"
    },
    "talks": [
      {
        "id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
        "created_at": "2023-05-24T19:38:36.870Z",
        "updated_at": "2023-05-24T19:38:36.870Z",
        "name": “Listen to iqram!)”,
        "description": "",
        "thumbnail_url": null,
        "created_by_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j3",
        "partner_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
        "price": null,
        "currency": null,
        "start_time": "2023-07-27T16:25:00.000Z",
        "schedule": null,
        "access": "anyone",
        "mic_behavior": "start_on",
        "end_time": null,
        "schedule_talk_id": null,
        "theme_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
        "subscriptions_allowed": true
      }],
        "error": null
    }

Remove talks in an organization's groups

DELETE /api/v1/partners/group_talks

Name	Description
group_id (required)	The id of the group
talk_ids	array of talk ids to be removed from the group.

curl -X “DELETE” "https://www.atsmalltalk.com/api/v1/partners/group_talks" 
-H 'Content-Type: application/json; charset=utf-8' 
-H 'Authorization: Bearer [YOUR TOKEN HERE]' 
-d "group_id=df6829ae-35bf-42ls-851e-sdfoijg82224j" (required)
-d “talk_ids=[df6829ae-35bf-42ls-851e-sdfoijg82224j, df6829ae-35bf-42ls-851e-sdfoijg82224j]” (required)

Sample response:

{
  “talk_groups”: [
    {
      “talk_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      “partner_id: "df6829ae-35bf-42ls-851e-sdfoijg82224j",
    },
    {
      “talk_id": "df6829ae-35bf-42ls-851e-sdfoijg82224j",
      “partner_id: "df6829ae-35bf-42ls-851e-sdfoijg82224j",
    }
],
  "error": null
    }

Talk join

Triggers when a user joins a talk.

Sample talk_join webhook:

{
  "event_name": "talk_join",
  "body": {
    "user_id": 'b1c9902d-bf9c-4a5c-811d-f23efbb431b3',
    "username": 'eartothenoise',
    "photo_url": 'https://cbtzdoasmkbbiwnyoxvz.supabase.co/storage/v1/object/public/avatars/36a2a71c-2c53-448e-bab4-f2b72758a150.jpg',
    "name": 'Matt Hamilton',
    "uid": null  
  }
}

Recording saved

Triggers when a recording has been saved.

Sample recording_saved:

{
  "event_name":"recording_saved",
  "body": {
    "talk_id":"8384bedb-e656-4d2e-8a6b-58673e794506",
    "url":"https://atsmalltalk.com/ti/8384bedb-e656-4d2e-8a6b-58673e794506"
  }
}

Transcription ready webhook

Triggers when a recording has been saved.

Sample transcription_ready:

{
  "event_name":"transcription_ready",
  "body": {
    "talk_id":"8384bedb-e656-4d2e-8a6b-58673e794506",
    "url":"https://atsmalltalk.com/ti/8384bedb-e656-4d2e-8a6b-58673e794506"
  }
}

Real time transcription webhook

Triggers when a caption gets added to the real time transcript.

Sample next_caption:

{
  event_name: "next_caption",
  body: {
    message: "hello",
    fullname: "Waganawa Chomusuke",
    avatar_url: "https://cbtzdoasmkbbiwnyoxvz.supabase.co/storage/v1/object/public/avatars/e33b7386-ab42-4b14-824a-d0bfbd193992.jpg",
    username: "chomusuke",
    timestamp: "2023-08-08T16:41:11.463Z",
    talkId: "42ea83e0-c16d-4c0e-b296-5c1b4cb8911d"
  }
}