neeto-integrations-nano

The neeto-integrations-nano provides support for third-party integrations to neeto applications. The nano exports the @bigbinary/neeto-integrations-frontend NPM package and neeto-integrations-engine Rails engine for development..

The engine handles the authentication, webhooks and token management for integrations with the following providers.

• Meta ( Facebook, Instagram, WhatsApp )
• Google ( Analytics, YouTube )
• Microsoft ( MS Teams)
• Zapier
• Twilio

Host can provide required permissions for a supported third-party integration, then engine will handle the authentication, token storing and refreshing for the host. Tokens, account details and webhook subscription details are stored in tables handled by the engine.

The frontend package provides components to handle integration card, steps, disconnect and other integration configuration page support.

Contents

1. Development with Host application
   • Engine
     • Installation
     • Details
     • neeto products currently using this engine
   • Frontend package
     • Installation
     • Usage
     • Product integrations
2. Instructions for publishing

Development with Host application

Engine

Installation

1. Add the gem to your Gemfile.

source "NEETO_GEM_SERVER_URL" do
  gem "neeto-integrations-engine"
end

2. Run bundle install

3. Add the required env variables to .env.development and update your secrets.yml. Refer OAuth Config for more details on specific integrations.

4. Import migrations to your project:

bundle exec rails neeto_integrations_engine:install:migrations

5. Add the migrations to the database:

bundle exec rails db:migrate

6. Add the Integrations List required to config/neeto_integrations.yml. Also, add the required integration(not natively supported by engine) as other_applications for post Integration UI support.

applications:
  - title: "Instagram Chat"
    service_name: Instagram
    provider: Facebook
    service_type: Social
    scope:
      - email
      - public_profile
      - pages_show_list
      - instagram_manage_messages
      - instagram_basic
other_applications:
  - title: "neetoDesk"
    service_name: neetoDesk
    service_type: Support
    provider: neeto

Refer the Oauth Config for list of supported provider, service_name and service_type.

7. Import data migration to update the integrations list with the newly added integration from config/neeto_integrations.yml:

bundle exec rails generate neeto_integrations_engine:integrations_list:update

Or manually execute the following command in all the environments to update the integrations list. Although the above approach is recommended.

bundle exec rails neeto_integrations_engine:integrations_list:update

8. Mount Neeto Integrations to your routes.rb:

mount NeetoIntegrationsEngine::Engine, at: "/neeto_integrations"

9. For SMS integrations (Twilio/Telnyx): draw the dev SMS routes in the host app's routes.rb. Skip this step if the app doesn't use the SMS integrations.

NeetoCommonsBackend::Routes.draw :dev_sms # Defined in neeto-commons-backend; local (dev/test) and transit envs only

In local and transit environments, the engine captures outbound SMS into Redis instead of calling Telnyx/Twilio. These routes (neeto-commons-backend >= 2.20.8) expose the captured messages at /smsbox and via api/v1/testing/sms for development and Playwright testing. No-op in all other environments.

Note: connecting the Telnyx/Twilio integration still requires real credentials — capturing only intercepts the outbound SMS, which are stored in Redis and shown in /smsbox instead of being sent through the provider.

To enable capturing, add the following to the .env.local file:

RECORD_SMS_DELIVERIES=true

10. Add association to User model:

has_many :auth_requests, class_name: "NeetoIntegrationsEngine::AuthRequest", dependent: :destroy

11. Add association to Organization model:

has_many :integrated_apps, class_name: "NeetoIntegrationsEngine::IntegratedApp", dependent: :destroy

12. If you want your integration to be specific to other model like User, Form , etc, add association as:

has_many :integrated_apps, as: :integrable, class_name: "NeetoIntegrationsEngine::IntegratedApp", dependent: :destroy

13. Add neeto_integrations_engine.organization.manage_integrations permission to your permissions.yml file which authorizes the user to manage organization level integrations.

Details

• Endpoints
• Errors
• MS Teams credentials and integration information
• Telnyx integration setup
• SMS logs

neeto products currently using this engine

Frontend package - @bigbinary/neeto-integrations-frontend

UI for integrations for all neeto products.

Installation

yarn add @bigbinary/neeto-integrations-frontend

Usage

Available components:

• Components
  • Card
  • Connect
  • Daily.co
  • Demo
  • DisconnectAlert
  • Finish
  • GoogleCalendar
  • Modal
  • Twilio
  • Telnyx
  • WalkthroughModal
  • Zoom
• Exports and Types

Product integrations

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.