Events - Transform JSON

Integrating CNC with your internal systems requires transforming CNC messaging JSON to and from a format that your system can understand.

Web1on1 / CitNOW Conversations provides a powerful Events API to ingest JSON payloads in foreign formats, per upstream provider native specification. You can build mappings using the Event Types API and use them to transform data for both inbound and outbound events. Use the powerful JSON-to-JSON transformation engine to transform external to internal fields to create contacts, conversations and messages.

Event Specification and Orchestration

The way to inform CN Conversations of external activity is to send a message to our Event Ingress API interface.

For the configured Event Types, upstream partners do not need to implement a sequence of API calls at their end to achieve the business process outcomes. Instead that orchestration is handled internally by CN Conversations and upstream partners need only to send a single message, in their native format.

In the diagram above, the upstream partner sends an event (for example, an appointment reminder event) in its native format, which is transformed into a conversation and event-type message, and processed as a conversation upsert.

In addition, the event may trigger one or more routing rules in the dealer account, configured by the dealership. These rules could start a bot, notify a team or send a templated message.

As illustrated above the flow of event specification and ingress is as follows:

1. An upstream partner specifies an Event Type.
2. Upstream provider calls the Events ingress API
3. Event payload is transformed into conversation message(s)
4. Message(s) trigger Event/Results Routing Rules
5. Routing Rules execute actions, deliver to targets

When to use Events

There are three ways you can transform Stedi transaction data (JSON) into a custom format: Stedi Mappings, writing custom code, and using an iPaaS platform. The approach you choose depends on your circumstances and preferences.

Mappings may be a good fit for your business when:

• Your system can natively produce and consume JSON payloads.
• You plan to do one-step transformations without multi-step processing.
• You want your business or operations team to manage mappings without engineering involvement.
• You want a solution that’s integrated with the Stedi platform.

Write to Conversations (Inbound Events)

You can also use Events to transform JSON from your business systems into the Conversations JSON format required to Web1on1's API. Inbound events, as a rule, should use a transformation to turn external data into conversation messages (of various message types), resulting in the payload for a conversation Upsert API call.

For example, an integrator may want to post Inbound event payloads such as

POST https://api.web1on1.chat/v2/events/>;

{
    "dealerId": "crazy-kangaroo-65",
    "msgText": "Hi Peter, your car is ready and scheduled for pickup on Thursday, June 7th.",
    "phone": "+1 206 555 0199",
    "email": "peter@example.com"
}

Note that all payload field values are internal to the DMS - no Web1on1 IDs are required.

The event type defines a JSONata transformation such as the following, to create the conversations Upsert payload:

{
    "organization": $organizationForExternalId(dealerId),
    "contact": {
        "profile": {
            "telephone": phone,
            "email": email
        }
    },
    "messages": [
        {
            "text": msgText,
            "role": "agent"
        }
    ]
}

Read from Conversations (Outbound Events)

The most common Mappings use case is transforming processed webhook data from Web1on1 into a custom JSON Schema for your business system.

You may want to transform Web1on1 events into a custom shape before sending them to your business system. For example, you may want to ingest resource update events into applications like Slack or Zapier to create internal alerts for your operations team.

You can use webhooks to automatically Ingest Web1on1 events - send transaction processed events to any API endpoint. Then, you can use the service.jsonata property to return the transformed output of the processed Conversation event.