NAV Navbar
  • Introduction
  • How to create events
  • Link to your Vyte page from your app
  • Getting free slots
  • Teams
  • API keys
  • Webhooks
  • Errors
  • Introduction

    The API provides useful functionalities such as:

    1. Create events in Vyte directly from your app
      1. You will first need to register as a "third party" app in Vyte (through an endpoint)
      2. Then you'll be able to link to Vyte to schedule an event will all the members of a team, project, task (we call that a "group")
      3. You'll be able to retrieve all the events related to that group
    2. Link to a Vyte page and pass parameters in the URL

    How to create events

    Register your app

    Examples

    https://api.vyte.in/thirdparties/new?name=superapp&contact_email=superman@superapp.com&contact_name=Super%20Man
    

    Result format 200 OK

    {
        "__v": 0,
        "createdAt": "2016-01-18T00:13:35.203Z",
        "updatedAt": "2016-01-18T00:13:35.203Z",
        "secret": "mols1p5ay6comkzj73ca",
        "name": "superapp",
        "_id": "569c2e2fa28cc30300778c4c",
        "contact": {
            "email": "superman@superapp.com",
            "name": "Super Man"
        }
    }
    

    Result format 400 Bad Request

    {}
    

    This endpoint registers your app as a third party app and lets you obtain your app_id.

    HTTP Request

    GET https://api.vyte.in/thirdparties/new

    Query parameters

    Parameter Type Required Description
    name string true Your application name
    contact_email string true Your e-mail address
    contact_name string false Your name

    The _id attribute in the response object is your app_id. You will need it to identify the events created from your app and retrieve them.

    Example

    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&agid=project_85fc5&et=vyte.in%20setup%20session&im=martin@vytein.com&in=Martin%20Saint-Macary&places=Skype%7Cmartin.saint-macary%7C%7CGoogle%20Hangouts%7Cmartin@vytein.com&em=Hi%20Martin,%20please%20find%20my%20suggestions%20for%20our%2015%20min%20call%20setup%20session%20on%20vyte.in.%20Best
    

    You can set different parameters for the event creation such as title, invitees, places, and message.

    You can link to Vyte using either the first step (/add_invitees), or the second step (/add_details). In both cases, all the parameters will be taken into account.

    If the user creating the event already has a Vyte account, you don't need to authenticate him. If he has an account but is not logged in, he will be redirected to the login screen. Once logged in, he will be redirected back to the event creation page.

    If you want to enable your users to create events with Vyte, without having a Vyte account, you need to authenticate their email with a simple token system.

    HTTP Requests

    GET https://www.vyte.in/add_invitees

    GET https://www.vyte.in/add_details

    URL Parameters

    Examples

    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c
    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&agid=project_85fc5
    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&cm=johndoe@john.com
    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&cn=John%20Doe
    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&ct=qsdfjklmdqsjfklmqdjsfklmdjsqklfmjdsqkmf
    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&em=Hello
    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&et=Meeting%20to%20resolve%20this%20task%20for%20that%20project
    https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&places=Skype
    
    Parameter Required Description
    aid true App ID: your app ID for Vyte. You get it when you register your app with GET /thirdparties/new
    agid false App Group ID: this is an id you will provide to Vyte, that you will use to identify a group of users such as a team, a project, etc.
    cm true/false Creator e-mail: optional if the user already has a Vyte account
    cn false Creator name: useful to auto set a title with the name of all the participants
    ct true/false Creator token: optional if the user already has a Vyte account
    em false Event message
    et false Event title
    im false Invitee e-mail(s), separated by a pipe (|)
    in false Invitee name(s), separated by a pipe (|). To be used with im, with emails and names listed in the same order
    places false Event places, with place name and address separated by a single pipe (|) and several places separated by a double pipe (||)

    Authentication

    To enable your users to create events with Vyte without having a Vyte account, you will need to provide cm (Creator e-mail) and ct (Creator token) parameters to the Vyte urls.

    Compute the token yourself

    Example in Node.js/Coffeescript

    crypto = require 'crypto'
    module.exports.computeToken = (email, secret) ->
      hmac = crypto.createHmac 'sha256', secret
      hmac.setEncoding 'hex'
      hmac.write(email)
      hmac.end()
      hmac.read()
    

    The Creator Token is computed from the Creator Email and your app_secret using the Hmac-sha256 algorithm. You can compute it yourself using the code on sidebar.

    Compute the token via the API

    Result format 200 OK

    {"token": "qsdfjklmdqsjfklmqdjsfklmdjsqklfmjdsqkmf"}
    

    Result format 400 Bad Request

    {}
    

    This endpoint gives the Creator Token you need for the Vyte urls.

    HTTP Request

    GET https://api.vyte.in/thirdparties/token

    Query parameters

    Parameter Type Required Description
    cm string true Creator e-mail
    secret string true Your app secret

    Obtain the list of events for a group of users

    Examples with one and two group IDs

    https://api.vyte.in/thirdparties/569c2e2fa28cc30300778c4c/groups/groupABC/events
    https://api.vyte.in/thirdparties/569c2e2fa28cc30300778c4c/groups/groupABC,groupDEF/events
    

    Result format 200 OK

    [
        {
            "_id": "569c3b6105dc780300951bd0",
            "key_store": "569c3b6105dc780300951bd7",
            "email": "reply-to-participants-to-meeting-for-project-vqdhhcxqd@vyte.in",
            "invitees_length": 3,
            "createdAt": "2016-01-18T01:09:53.477Z",
            "updatedAt": "2016-01-18T01:10:05.670Z",
            "alias": "alias_web_522984fb35eaa70200000007_1453079356811",
            "app_url": "https://www.vyte.in",
            "lang": "en",
            "locale": "en",
            "timezone": "Europe/Paris",
            "title": "Meeting for project",
            "__v": 3,
            "version": 3,
            "third_party": {
                "app": "569c2e2fa28cc30300778c4c",
                "group_ids": ["project_85fc5"],
                "name": "superapp"
            },
            "ics_sequence": 0,
            "confirmed": {
                "updated_at": null,
                "flag": false
            },
            "places": [
                {
                    "createdAt": "2016-01-18T01:09:53.290Z",
                    "updatedAt": "2016-01-18T01:10:05.665Z",
                    "name": "Appear.in",
                    "address": "http://appear.in/cool-meeting",
                    "icon": "P",
                    "_id": "569c3b6105dc780300951bd3",
                    "votes": {
                        "no": [],
                        "yes": [
                            {
                                "_id": "569c3b6105dc780300951bd6",
                                "createdAt": "2016-01-18T01:09:54.161Z",
                                "updatedAt": "2016-01-18T01:10:05.664Z",
                                "created_by": {
                                    "user": "522984fb35eaa70200000007"
                                }
                            }
                        ]
                    },
                    "created_by": {
                        "user": "522984fb35eaa70200000007"
                    },
                    "source": "Appear.in"
                }
            ],
            "dates": [
                {
                    "createdAt": "2016-01-18T01:10:05.665Z",
                    "updatedAt": "2016-01-18T01:10:05.665Z",
                    "date": "2016-01-22T10:00:00.000Z",
                    "end_date": "2016-01-22T11:00:00.000Z",
                    "_id": "569c3b6da28cc30300778c72",
                    "votes": {
                        "no": [],
                        "yes": [
                            {
                                "_id": "569c3b6da28cc30300778c74",
                                "created_by": {
                                    "user": "522984fb35eaa70200000007"
                                }
                            }
                        ]
                    },
                    "created_by": {
                        "user": "522984fb35eaa70200000007"
                    },
                    "all_day": false
                },
                {
                    "createdAt": "2016-01-18T01:10:05.665Z",
                    "updatedAt": "2016-01-18T01:10:05.665Z",
                    "date": "2016-01-22T15:00:00.000Z",
                    "end_date": "2016-01-22T16:00:00.000Z",
                    "_id": "569c3b6da28cc30300778c73",
                    "votes": {
                        "no": [],
                        "yes": [
                            {
                                "_id": "569c3b6da28cc30300778c76",
                                "created_by": {
                                    "user": "522984fb35eaa70200000007"
                                }
                            }
                        ]
                    },
                    "created_by": {
                        "user": "522984fb35eaa70200000007"
                    },
                    "all_day": false
                }
            ],
            "declines": [],
            "messages": [
                {
                    "from": "martin.saintmac@gmail.com",
                    "createdAt": "2016-01-18T01:09:53.290Z",
                    "updatedAt": "2016-01-18T01:10:05.664Z",
                    "body": "Another meeting for that project",
                    "_id": "569c3b6105dc780300951bd4",
                    "created_by": {
                        "user": "522984fb35eaa70200000007"
                    }
                }
            ],
            "invitees": [],
            "created_by": {
                "full_name": "Martin Saint-Macary",
                "picture_url": "https://lh3.googleusercontent.com/-PWeG6KmcyVw/AAAAAAAAAAI/AAAAAAAAJa4/kcQXhsmUmTQ/photo.jpg",
                "user": "522984fb35eaa70200000007",
                "email": "martin.saintmac@gmail.com"
            }
        },
        {
            "_id": "569c3afaa28cc30300778c69",
            "key_store": "569c3afba28cc30300778c71",
            "email": "reply-to-participants-to-meeting-martin-saint-macary-martin-saint-macary-awtdmgsnm@vyte.in",
            "invitees_length": 2,
            "createdAt": "2016-01-18T01:08:11.524Z",
            "updatedAt": "2016-01-18T01:08:12.691Z",
            "alias": "alias_web_522984fb35eaa70200000007_1453079284514",
            "app_url": "https://www.vyte.in",
            "lang": "en",
            "locale": "en",
            "timezone": "Europe/Paris",
            "title": "Meeting Martin Saint-Macary, Martin Saint-Macary",
            "__v": 1,
            "version": 1,
            "third_party": {
                "app": "569c2e2fa28cc30300778c4c",
                "group_ids": ["project_85fc5"],
                "name": "superapp"
            },
            "ics_sequence": 0,
            "confirmed": {
                "updated_at": null,
                "flag": false
            },
            "places": [
                {
                    "createdAt": "2016-01-18T01:08:10.933Z",
                    "updatedAt": "2016-01-18T01:08:12.688Z",
                    "name": "Skype",
                    "address": "martin.saint-macary",
                    "_id": "569c3afaa28cc30300778c6c",
                    "votes": {
                        "no": [],
                        "yes": [
                            {
                                "_id": "569c3afba28cc30300778c6f",
                                "createdAt": "2016-01-18T01:08:12.688Z",
                                "updatedAt": "2016-01-18T01:08:12.688Z",
                                "created_by": {
                                    "user": "522984fb35eaa70200000007"
                                }
                            }
                        ]
                    },
                    "created_by": {
                        "user": "522984fb35eaa70200000007"
                    },
                    "source": "app"
                },
                {
                    "createdAt": "2016-01-18T01:08:10.934Z",
                    "updatedAt": "2016-01-18T01:08:12.689Z",
                    "name": "Google Hangouts",
                    "address": "martin@vytein.com",
                    "_id": "569c3afaa28cc30300778c6b",
                    "votes": {
                        "no": [],
                        "yes": [
                            {
                                "_id": "569c3afba28cc30300778c70",
                                "createdAt": "2016-01-18T01:08:12.688Z",
                                "updatedAt": "2016-01-18T01:08:12.688Z",
                                "created_by": {
                                    "user": "522984fb35eaa70200000007"
                                }
                            }
                        ]
                    },
                    "created_by": {
                        "user": "522984fb35eaa70200000007"
                    },
                    "source": "app"
                }
            ],
            "dates": [],
            "declines": [],
            "messages": [
                {
                    "from": "martin.saintmac@gmail.com",
                    "createdAt": "2016-01-18T01:08:10.934Z",
                    "updatedAt": "2016-01-18T01:08:12.688Z",
                    "body": "Hi Martin, please find my suggestions for our 15 min call setup session on vyte.in. Best",
                    "_id": "569c3afaa28cc30300778c6d",
                    "created_by": {
                        "user": "522984fb35eaa70200000007"
                    }
                }
            ],
            "invitees": [],
            "created_by": {
                "full_name": "Martin Saint-Macary",
                "picture_url": "https://lh3.googleusercontent.com/-PWeG6KmcyVw/AAAAAAAAAAI/AAAAAAAAJa4/kcQXhsmUmTQ/photo.jpg",
                "user": "522984fb35eaa70200000007",
                "email": "martin.saintmac@gmail.com"
            }
        }
    ]
    

    Result format 400 Bad Request

    {}
    

    This endpoint gives the Creator Token you need for the Vyte urls. This endpoint lists the events created from your app for a group of users.

    HTTP Request

    GET https://api.vyte.in/thirdparties/<app_id>/groups/<group_id>/events

    Path parameters

    Parameter Type Required Description
    app_id string true Your app id
    group_ids string true The custom group id you want the list for. If you want events belonging to several group IDs, separate them with a comma.

    Booking an appointment

    Header

    Content-Type: application/json
    

    Example of body

    {
      "confirmed":{"flag": true},
      "created_by":{"email": "use.name@domain.com"},
      "dates":[{"all_day": false, "date": "2017-11-10T11:00:00.000Z", "end_date": "2017-11-10T12:00:00.000Z"}],
      "invitees":[{"full_name": "Person booking a slot name", "email": "jean.dupont@domain.com", "phone": "0601020304"}],
      "lang":"fr",
      "locale":"fr",
      "messages":[{"body": "I’m booking appointment about this"}],
      "places":[{"name": "Office name", "address": "12 rue de Rivoli, 75004, Paris, France"}],
      "timezone":"Europe/Paris",
      "title":"Appointment about topic",
      "vyteme":true,
      "third_party": {
          "ct": "creator_token",
          "app": "app_id"
      }
    }
    

    HTTP Request

    POST https://api.vyte.in/events

    Comparing with the example on the sidebar of this page:

    Link to your Vyte page from your app

    You can make booking on your Vyte page even faster by setting pretty much everything but the dates directly in the URL. This could also prove interesting when adding a link to your Vyte page in an emailing campaign.

    You don't need to register your app to do that, however you will need to have set up a Vyte page with a pro Vyte account.

    Appointment duration

    You can set the duration (in minutes) of an appointment directly in the URL as such:

    URL parameters

    Example

    https://www.vyte.in/emma/20?et=Meeting%20%7B%7Binvitee%7D%7D&cm=john.doe@domain.com&cn=John%20Doe&places=Skype%7Cjohn%7C%7CGoogle%20Hangouts%7Cjoh.doe@domain.com&em=Hello
    
    

    You can use those parameters with the URL of your Vyte page (ex: https://vyte.in/acme)

    Parameter Required Description
    cn false Creator name: useful to auto set a title with the name of all the participants
    cm false Creator e-mail: if you set cn your invitees won't be prompted to put their name and emails or to login with Google to book you. We highly recommend to populate cm along.
    cc false Creator company: make sure to enable the "Ask for company" setting in your advanced Vyte page settings.
    cp false Creator phone number: make sure to enable the "Ask for phone number" setting in your advanced Vyte page settings.
    em false Event message
    et false Event title
    places false Event places: place name and address separated by a single pipe (|) and several places separated by a double pipe (||)

    Getting free slots

    This section of the documentation explains how to retrieve free slots for Vyte users to help you schedule your meetings.

    Getting slots in bulk

    Examples

    https://api.vyte.in/slots?duration=60&emails=user.name@domain.com&from=2017-11-10&to=2017-11-10
    

    Response on success: 200 OK

    {
      "slots": [
        {
          "start": {
            "dateTime": "2017-11-10T10:00:00.000+02:00"
          },
          "end": {
            "dateTime": "2017-11-10T11:00:00.000+02:00"
          }
        },
        {
          "start": {
            "dateTime": "2017-11-10T11:00:00.000+02:00"
          },
          "end": {
            "dateTime": "2017-11-10T12:00:00.000+02:00"
          }
        },
      ]
    }
    
    

    HTTP request

    GET /slots

    Query parameters

    Parameter Type Required Description
    duration number true Duration of the appointment in minutes
    emails string true Address of the person you want to book an appointment with. It has to be the address that person is signed up with on Vyte
    from string true Date from when you want to get available slots (included) formatted as YYYY-MM-DD
    to string true Date until when you want to get available slots (included) formatted as YYYY-MM-DD

    Getting slots grouped by days

    Examples

    https://api.vyte.in/slots/days?duration=30&emails=user.name@domain.com&from=2017-12-18&to=2017-12-18
    

    Response on success: 200 OK

    {
      "days": {
        "2017-12-18": {
          "slots": [
            {
              "start": {
                "dateTime": "2017-12-18T09:30:00.000+02:00"
              },
              "end": {
                "dateTime": "2017-12-18T10:00:00.000+02:00"
              }
            },
            {
              "start": {
                "dateTime": "2017-12-18T10:00:00.000+02:00"
              },
              "end": {
                "dateTime": "2017-12-18T10:30:00.000+02:00"
              }
            },
          ]
          }
        }
     }
    
    
    

    Just add /days to the previous end point to get the results formatted as a dictionary where keys are days formatted as YYYY-MM-DD.

    For completeness, we report here the relative documentation.

    HTTP request

    GET /slots/days

    Query parameters

    Parameter Type Required Description
    duration number true Duration of the appointment in minutes
    emails string true Address of the person you want to book an appointment with. It has to be the address that person is signed up with on Vyte
    from string true Date from when you want to get available slots (included) formatted as YYYY-MM-DD
    to string true Date until when you want to get available slots (included) formatted as YYYY-MM-DD

    Getting next availability if no slots in the requested time frame

    Response on success: 200 OK

    {
      "nextAvailability": {
        "availableDate": "2017-12-18",
        "availableSlot": {
          "start": {
            "dateTime": "2017-12-18T09:30:00+01:00"
          },
          "end": {
            "dateTime": "2017-12-18T10:00:00+01:00"
          }
        }
      },
      "days": {},
    }
    
    
    

    If the user you are requesting available slots for has no availability in the requested time frame, Vyte’s API will tell you their next availability.

    In this case you will have slots: [] if you’ve used /slots (1.1) or days: {} for /slots/days (1.2)

    The response will include a nextAvailability object formatted as in the example.

    Teams

    Teams are a way to group several users for 2 purposes:

    1. Pay for multiple pro subscriptions with only 1 bill.

    2. Share a branding across multiple users

    Teams can be used for deploying Vyte in an actual team, but they can also be used to integrate Vyte into another app or service and pay for your users.

    When you create a team, you can then invite other people to it. If they are not users yet, they will be added to the team as soon as they have signed up.

    Once added to the team theses users will be upgraded to a PRO plan automatically, granting them access to all the features of Vyte. The team admin is billed for them.

    If the team admin creates a brand (or has created one), their custom subdomain, background and logo will be applied to all the members of the team.

    Creating a team

    To create a team, just go to the team tab of your Vyte settings.

    Private teams

    If you use a team to integrate Vyte into your app or service, and pay for your users, you probably don't want your users to be able to see each other. In that case you probably want to set your team to private.

    This is a manual task for now, so just ping us on the chat window that is on the bottom right corner of Vyte's landing pages and web app, and mention that you are a developer using our API.

    Getting a team

    Example

    GET https://api.vyte.in/users/organizations
    

    Teams are also called organizations. To get all the information about your team, you can do an API call in your browser

    Authentication

    Just make sure you are connected to Vyte in that browser as the team admin.

    HTTP Request

    GET /users/organizations

    Response

    Some interesting fields of the response body:

    Field Type Definition
    _id String The id of your team / organization
    name String The name of your team
    private Boolean Wether your team is private or not. Default to false
    members Array The members of your team, including its admin.
    admins Array The admin of your team.

    Basic example:

    https://www.vyte.in/teams/14ce14c8a8ced358c78a5c231d/join
    

    If you want to integrate Vyte into your app or service, you'll probably want to have access to your users availability. For that you will need to get them to sign up to Vyte.

    This can't be done purely via API as your users will need to connect either their Google or Microsoft Office 365 calendar, through Google / Microsoft OAuth 2 flows, and these need to happen in the frontend.

    To do that you can point them to the link to join your team:

    GET https://www.vyte.in/teams/:team_id/join

    Where :team_id is the id you got when getting your team

    This link will let them sign up for Vyte and join automatically join your team as soon as they have signed up.

    If they were already Vyte users, they will just automatically join your team by visiting this link.

    Using a custom design on that signup page.

    Example with a custom subdomain:

    https://mycoolapp.vyte.in/teams/14ce14c8a8ced358c78a5c231d/join
    

    If you want that sign up page to showcase your brand, no problem, just set up your brand and subdomainin your Vyte's settings and use that subdomain instead of www

    Knowing when a user joins your team

    You probably want to know when a user joins your team after you have pointed them to the link to join your team on Vyte.

    For that, just subscribe to the user.joined webhook

    Matching your app users to Vyte's users

    Example with a custom subdomain and an extid

    https://mycoolapp.vyte.in/teams/14ce14c8a8ced358c78a5c231d/join?extid=user55542
    

    When pointing one of your users to sign up to Vyte, you can pass an extid query Parameter. This extid can be whatever id you need to be able to match a Vyte user to your users when getting called back by the user.joined webhook.

    API keys

    Some endpoints shuch as /hooks needs to be authenticated with api keys.

    Get an API key for your team

    Example

    GET https://api.vyte.in/api/keys/team
    

    Response on success:

    200 OK

    {
      "__v": 0,
      "createdAt": "2018-01-04T11:49:28.220Z",
      "updatedAt": "2018-01-04T11:49:28.220Z",
      "key": "i2xthzol66q9zucx04ta4ljptg1bd26ctuf3curhtufoaxf8t8",
      "organization": "14ce14c8a8ced358c78a5c231d",
      "user": "14ce14c8a8ced3001c8a5c231d",
      "_id": "5a4e14c8a8ced3001c8a5c231d",
      "scope": "team"
    }
    

    Get an API key for that team by accessing /api/keys/team

    Make sure you have logged in with the Vyte account that is the admin of that team before that.

    If you access that link several times you will get the same API key. To get a new one you will need to delete it first and then get a new one.

    HTTP request

    GET /api/keys/team

    Response object main fields:

    Field Meaning
    key this is the key you will need to use to authenticate.
    _id the id of this API key. You will need it to delete / revoke this API key.

    Delete an API key

    Example

    DELETE https://api.vyte.in/api/keys/:5a4e14c8a8ced3001c8a5c231d
    

    Response on success:

    204

    HTTP request

    DELETE /api/keys/:key_id

    where :key_id is the _id property of your key.

    Authenticating a request with an API key

    There are 2 ways of doing so: using the api_key query param or the Authorization header.

    Authenticating using the query param

    Example

    GET https://api.vyte.in/api/keys/team?api_key=i2xthzol66q9zucx04ta4ljptg1bd26ctuf3curhtufoaxf8t8
    

    Just add an api_key query param, set to the key obtained above, to the URL of your request

    Authenticating using the Authorization header

    Example

    GET https://api.vyte.in/api/keys/team
    
    HEADERS:
    Content-Type: application/json
    Authorization: i2xthzol66q9zucx04ta4ljptg1bd26ctuf3curhtufoaxf8t8
    

    Just add an Authorization header, set to the key obtained above, to your request.

    Webhooks

    Available webhooks

    When registering for webhooks, you register for actions on resources. Actions are often called "events" in the webhooks terminology, but since Vyte's main resource is called "Event" we decided to name them action.

    Event resource

    This is the main resource on Vyte. An event is a meeting, 1-on-1 or group. It can be already confirmed, or still in the planing phase.

    Usually an event is created, then confirmed and sometimes updated or cancelled.

    event.created

    When an event has been created

    event.confirmed

    When an event has been confirmed which means a date and / or place have been decided.

    Some events can be created already confirmed. In this case both event.created and event.confirmed actions are fired.

    event.updated

    When an event that was already confirmed has ben edited an reconfirmed. Usually the final date and / or place has been changed but there is no guarantee of it.

    event.cancelled

    When an event, confirmed or not, has been cancelled.

    User resource

    A user is someone that has signed up to Vyte.

    user.joined

    When a user has joined a team using a link such as https://yourapp.vyte.in/teams/1234/join . If you have passed us an external id from your app extid as a query parameter, you will get it back as the resource.account.organization.extid property

    Authentication for Webhooks

    To use webhooks you need to have a Vyte team and an API key for your team

    All requests require to be authenticated

    Creating a webhook

    Example

    POST https://api.vyte.in/hooks
    

    Body

    {
      "action": "event.cancelled",
      "target_url": "https://api.example.com/hooks/12345"
    }
    

    Response on success: 201 Created

    {
      "__v": 0,
      "createdAt": "2018-01-04T15:00:58.486Z",
      "updatedAt": "2018-01-04T15:00:58.486Z",
      "organization": "14ce14c8a8ced358c78a5c231d",
      "scope": "team",
      "action": "event.cancelled",
      "target_url": "https://api.example.com/hooks/12345",
      "_id": "5a4e41aaa8ced3001bf5da77"
    }
    

    HTTP request

    POST /hooks

    Request body

    Field Type Mandatory Definition
    action String true The action that you want to be aware of
    target_url String true The URL you want to be called at when the action occurs. This must be a https url.

    The action field is often called event in the Webhooks terminology. As Events are the main resource on Vyte's API, we named that field action to avoid confusion.

    Getting a webhook

    Example

    GET https://api.vyte.in/hooks/5a4e41aaa8ced3001bf5da77
    

    Response on success: 200 OK

    {
      "__v": 0,
      "createdAt": "2018-01-04T15:00:58.486Z",
      "updatedAt": "2018-01-04T15:00:58.486Z",
      "organization": "14ce14c8a8ced358c78a5c231d",
      "scope": "team",
      "action": "event.cancelled",
      "target_url": "https://api.example.com/hooks/12345",
      "_id": "5a4e41aaa8ced3001bf5da77"
    }
    

    HTTP request

    GET /hooks/:hook_id

    where :hook_id is the _id of the webhook obtained when creating the webhook.

    Updating a webhook

    Example

    PUT https://api.vyte.in/hooks/5a4e41aaa8ced3001bf5da77
    

    Body

    {
      "action": "event.updated",
      "target_url": "https://api.example.com/hooks/54321"
    }
    

    Response on success: 200 OK

    {
      "__v": 0,
      "createdAt": "2018-01-04T15:00:58.486Z",
      "updatedAt": "2018-01-04T15:00:58.486Z",
      "organization": "14ce14c8a8ced358c78a5c231d",
      "scope": "team",
      "action": "event.updated",
      "target_url": "https://api.example.com/hooks/54321",
      "_id": "5a4e41aaa8ced3001bf5da77"
    }
    

    HTTP request

    PUT /hooks/:hook_id

    where :hook_id is the _id of the webhook obtained when creating the webhook.

    Request body

    Field Type Mandatory Definition
    action String true The action that you want to be aware of
    target_url String true The URL you want to be called at when the action occurs. This must be a https url.

    Deleting a webhook

    Example

    DELETE https://api.vyte.in/hooks/1234
    

    Response on success: 204 No Content

    HTTP request

    DELETE /hooks/:hook_id

    where :hook_id is the _id of the webhook obtained when creating the webhook.

    Listing all your webhooks

    Example

    GET https://api.vyte.in/hooks
    

    Response on success: 200 OK

    {
      "hooks": [
        {
          "__v": 0,
          "createdAt": "2018-01-04T15:00:58.486Z",
          "updatedAt": "2018-01-04T15:00:58.486Z",
          "organization": "14ce14c8a8ced358c78a5c231d",
          "scope": "team",
          "action": "event.cancelled",
          "target_url": "https://api.example.com/hooks/12345",
          "_id": "5a4e41aaa8ced3001bf5da77"
        }
      ]
    }
    

    HTTP request

    GET /hooks

    returns a hooks array.

    Getting a webhook call

    Example:

    POST https://api.example.com/hooks/12345
    

    HEADERS:

    Content-Type: application/json
    

    BODY:

    {
      "action": "event.cancelled",
      "resource": {
        "cancelled": "2017-12-01T12:05:00.000Z",
        "confirmed":{"flag": true},
        "created_by":{"email": "use.name@domain.com"},
        "dates":[{"all_day": false, "date": "2017-11-10T11:00:00.000Z", "end_date": "2017-11-10T12:00:00.000Z"}],
        "invitees":[{"full_name": "Person booking a slot name", "email": "jean.dupont@domain.com", "phone": "0601020304"}],
        "lang":"fr",
        "locale":"fr",
        "messages":[{"body": "I’m booking appointment about this"}],
        "places":[{"name": "Office name", "address": "12 rue de Rivoli, 75004, Paris, France"}],
        "timezone":"Europe/Paris",
        "title":"Appointment about topic",
        "vyteme":true
      },
      "team": "14ce14c8a8ced358c78a5c231d"
    }
    

    When an action you have subscribed a webhook for is performed on a resource, Vyte will call your API at the target_url you provided.

    HTTP request

    POST target_url Vyte will perform a POST request at the target_url provided

    Request body

    The request body is an array of objects representing actions that have happened on a resource linked to your api key. You can assume this array will always have a length of 1 but that may change in the future.

    Object properties

    Property Type Always present Definition
    action String true The action that happened on the resource. ex: event.cancelled
    team String false The id of the team linked to that action
    user String false The id of the user linked to that action
    resource Object true The resource that has been updated by this action. An event object for instance.

    Errors

    The Vyte API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request was somehow incorrect. Make sure you include the right parameters in the query, body or headers
    401 Unauthorized -- This request requires to be authenticated and you are not
    403 Forbidden -- You are authenticated but you are not allowed to perform this Request
    404 Resource not found -- We couldn't find the resource you are trying to access
    500 Internal server error -- For some reason your request triggered an internal error in our API. Contact us to know more about it.
    503 Request timed out -- Our API servers didn't respond in time and the request timed out. If this happens repeatedly, contact us.