The key details of how API protocols are used in a HeyConnect Configuration




HeyConnect & Standard API Protocols 

HeyConnect takes the hard work out of an API integration while still being based on standard REST methods POST, PATCH, DELETE.

All the HeyConnect create events should be mapped to a POST request in your API. These require the most complete configuration as the response body provided by your API contains the essential details needed in the integration. 

 

All HeyConnect update events should be mapped to PATCH requests in your API (where possible). HeyConnect will consume the success / failure and react accordingly. In most instances a PATCH will not change any of the key details required (e.g. join URL’s) there is no need to configure the response body element. If a key details required (e.g. join URL’s) is altered then HeyConnect can consume the response body if configured. 

Note: PUT requests can be configured in instances where the API endpoint has been coded to affect partial data point changes.

 

All HeyConnect delete events should be mapped to DELETE requests in your API. HeyConnect will consume the success / failure and react accordingly. HeyConnect does not consume the response body so no configuration of this is required. 

 

 

Dealing with Different Authentications Styles

HeyConnect presently supports OAuth2 standards and we will add support for other Authorisation standard’s as the need arises. If your API requires a different standard please let us know by emailing us at integrations@heysummit.com

The authentication configuration allows us to identify the authentication style and prompt the user for the required details that are then passed into the HeyConnect system to facilitate authenticated communication. 

 

 

HeyConnect Trigger Event Configuration

Within HeyConnect there must be a configuration for all the must have events listed in HeyConnect: The Basics of a HeySummit Integration

Each configuration element consists of three key attributes:

  1. The Trigger Event precipitated by HeySummit (e.g. create_talk).
  2. The Request Config that converts the HeySummit request into the language of the partner API (e.g. create_webinar).
  3. The Response Config that converts the partner API response into the language of the HeyConnect API and returns data to HeySummit (e.g. receive webinar URL).

 

Event Type

Each event type must have only one corresponding Request and Response configuration.

 

Request Configuration

The ‘Request Configuration’ is the mechanism that converts the HeySummit request into the format required the partner API. It consists of 5 distinct elements:

  1. The API URL to be used for sending the request (highlighted in yellow).
  2. Any additional URL parameters are configured against the  url_params any additional query parameters are configured against the url_params (highlighted in light orange).
  3. The type of API call being used in the request (highlighted in orange).
  4. The elements coming from HeySummit systems are contained in the field mappings where these relate to your API these must be converted into the field names used in your API (highlighted in magenta).
    • Note: If the value does not relate to your API then it should be removed from the configuration. 
  5. The additional fields represent the values that are required in your API for it to supply a successful response. These fields/attributes are not specifically part of the HeySummit integration as HeySummit has no corresponding concept .Thus they need to be ‘hard coded’ to the most appropriate value, (highlighted in blue).
    • Note: Remember to edit/remove all additional fields in the example configuration.

 

 

Response Configuration

The ‘Response Configuration’ represents all the attributes that the HeySummit system must record for the integration to be functional. If a key attribute is missing then the integration will not be complete and will error at some essential point. E.g. 

 

 

All Create API calls triggered will contain some attribute that needs to be recorded back to HeySummit via the HeyConnect configuration so that later communication (PATCH,DELETE) can be communicated or key functionality can be triggered. 

Update & Delete API calls will contain additional data points for path and query parameters. HeyConnect will pass these into the API call URL in order to identify the correct object e.g.

 

 

Additional Query parameters are dealt with via additional configuration

Update & delete API calls do not contain additional data in the response that is not already known therefore HeyConnect will just consume a ‘Success’ or ‘Failure’. Where a ‘Failure’ is encountered HeySummit will be informed and a new attempt scheduled for a later date-time. Where a response configuration includes no values {"field_mappings": []} then HeyConnect will consume the ‘Success’ - 'Failure’ only. 

 

HeySummit (HeyConnect) Minimum Field Configuration

 

Create Talk

HeySummit will send the following minimum field values to the HeyConnect system so the ‘request configuration’ must have a mapping recorded for:

  • 'title'
  • 'description'
  • 'date'
  • 'duration'

Note: ‘Disable Emails'. If your system supports emails being disabled per webinar session then this should always be set to ‘do not send emails’ since these are managed at the HeySummit end.  

 

HeySummit must receive the following minimum details (and only these details) for the integration to function so the ‘response configuration’ must have a mapping recorded that includes:

  • ‘webinar_id’
  • ‘organizer_url’
  • ‘attendee_url’ (Note: the attendee url is a fall back URL used only if a unique URL per attendee is not supplied on registration)  

  

Create Speaker

HeySummit will send the following field values to the HeyConnect system so the ‘request configuration’ could have a mapping recorded for (the must have values are indicated):

  • ‘webinar_id’ (must have)
  • 'name_prefix'
  • 'name_suffix'
  • 'first_name' (must have)
  • 'last_name'
  • 'company'
  • 'company_title'
  • 'bio'
  • 'company_url'
  • 'twitter_url'
  • 'facebook_url'
  • 'linkedin_url'
  • 'instagram_url'

Note: If your system distinguishes participants and their access rights by ‘type’ then the definition and code should be configured as an ‘addtional_field’.  E.g.

  "additional_fields":[

      {

         "Name":"participant type",

         "value":3

      },

 

HeySummit must receive the following minimum details (and only these details) for the integration to function so the ‘response configuration’ must have a mapping recorded that includes:

  • speaker_join_url (this will supersede any value previously sent and is recorded against the attendee so that unique identification of the attendee can be achieved)

 

Create (Add) Attendee

HeySummit will send the following minimum field values to the HeyConnect system so the ‘request configuration’ must have a mapping recorded for:

  • ‘webinar_id’
  • ‘email’
  • ‘name’

 

HeySummit must receive the following minimum details (and only these details) for the integration to function so the ‘response configuration’ must have a mapping recorded that includes:

  • ‘attendee_join_url’ (this will supersede any value previously sent and is recorded against the attendee so that unique identification of the attendee can be achieved) 

 

Example Config

Please download an example configuration and complete with your API endpoints and variables.

 

Support, Testing & Go Live 

Once you have completed your integration contact us at integrations@heysummit.com supplying your configuration in a JSON format. Our technical support team will analyse the configuration and get back to you if there are any obvious omissions.

 

Once the configuration passes analysis we will install it in a test environment and perform an end to end test. Given that test is successful our Customer Success team will be in touch to create release material and arrange a beta trial. At this point we will need you to supply the material required for a marketing release of the integration. This consists of your preferred

  • Company Logo
  • System Tag Line
  • Short Product Description including
  • the benefits of using your product with the integration with HeySummit
  • Any information relating to the exact integrated product if your product has alternative reversion 
  • The price point of the integrated solution
  • The company/product URL you would like to refer interested users to
  • The Sales Email / Form you would like referrals forwarded to
  • The Support Email / Form you would like queries relating to the integration sent to

 

Questions

We are happy to clarify any details or answer any questions you may have.

 

Email: integrations@heysummit.com