API Examples

Provides some examples of using APIs.

The following are code examples that demonstrate using the Communicate API.

Email transactional send

  1. Create an email communication example in the Samples project.
  2. Add a data source (this step can be skipped because later you can send data directly in the API request, but it helps during email design).

  3. Create the client credentials (this can be done in Account Settings).

    Example data:

    CustomerId: sa11bb, 
ClientId: sa11bb.11122223333444@comunnicate.engageone.co
Secret: aabbcc
  4. Add the sender email address example.email@example.com (this can be done in Account Settings).

  5. Get the authorization token (https://docs.api.communicate.engageone.co/users.html#/auth/authenticate).

    Request: https://usersapi.communicate.engageone.co/authenticate
Body: 
    {    
        "client_id": "sa11bb.11122223333444@comunnicate.engageone.co",
        "secret": "aabbcc",
        "customer_id": "sa11bb"
    } 
Example response: 
    "eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f"

  6. Send campaign transactional v2 (the full request can be found here: https://docs.api.communicate.engageone.co/#/campaigns/transactionalCampaignV2)

    Request: https://api.us-east-1.communicate.engageone.co/campaigns/v2/ExampleCampaign/transactional
Headers: 
    {     PB-Customer-Id: "sa11bb"
          Authorization: "Bearer eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f" 
    } 
Body: 
{ 
"communication": "Example",
"dataset": [ 
{  
    "customer_email": "example.receiver@example.com", 
    "name": "John" 
} 
], 
    "email_json_path": "customer_email", 
    "sender": "example.email@example.com", 
    "sender_name": "Sender Name", 
    "reply_to": example.email@example.com, 
    "subject": "Sample Subject", 
    "project": "Samples", 
    "ignore_missing_fields": true 
} 
Example Response: 
{ 
    "send_id": "asd-213-asd-123-asd3223d3" 
}

  7. To check if the email was sent successfully, use the received sendId in this request. (https://docs.api.communicate.engageone.co/#/campaigns/getTransactionalCampaignStatus)

    Request: https://api.us-east-1.communicate.engageone.co/campaigns/v2/transactional/asd-213-asd-123-asd3223d3
Headers: 
{ 
    PB-Customer-Id: "sa11bb" 
    Authorization: "Bearer eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f" 
}  
Example Response: 
{ 
    "sendId": "abd9f7b7-051c-40cc-b748-487a61ae5af0", 
    "status": "success" }

Generating a video PURL

  1. Create the Example_video video communication in the Samples project.
  2. Add Example.csv as the data source.
  3. Create client credentials (this can be done in Account Settings).

    Example data:

    CustomerId: sa11bb, 
ClientId: sa11bb.11122223333444@comunnicate.engageone.co
Secret: aabbcc

  4. Get the authorization token (https://docs.api.communicate.engageone.co/users.html#/auth/authenticate).

    Request: https://usersapi.communicate.engageone.co/authenticate
Body: 
    {
        "client_id": "sa11bb.11122223333444@comunnicate.engageone.co",
        "secret": "aabbcc",
        "customer_id": "sa11bb"
    }
Example response:  
"eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f"

  5. Get the data source ID (https://docs.api.communicate.engageone.co/#/data/listData)

    Request: https://api.us-east-1.communicate.engageone.co/data?ds_name_starts_with=Example
Headers:
    {
        PB-Customer-Id: "sa11bb"
        Authorization: "Bearer eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f"
    }
Example response:
    {
        "data": [
                    {
                        "DataSourceStatus": "complete",
                        "Id": "21s21s21s-43ea-4ad9-894b-s212s2",
                        "LastModified": 1682584955,
                        "Name": "Example",
                        "Size": 173, 
                        "Type": "csv" 
                    } 
                ] 
    }

  6. Get video communication ID (https://docs.api.communicate.engageone.co/video-channel.html#/Video%20Communication/get_data_project__ProjectName__communication__CommunicationName_)

    Request: https://api-ui.engageone.video/data/project/Samples/communication/Example_video
Headers:
    {
        PB-Customer-Id: "sa11bb"
        Authorization: "Bearer eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f"
    }
Example response:
    {
        "_id": "12421fdfsncjdsnj",
        "projectName": "Samples",
        "communicationName": "Example_video",
        "teamId": "sa11bb",
        "meta": 
        {    "createdAt": "2023-04-27T06:23:42.074Z",
             "updatedAt": "2023-04-27T08:44:50.663Z"
        },
        "config": 
        {
            ...
        }
    }

  7. Video purls generation (https://docs.api.communicate.engageone.co/#/data/getVideoDataUUID)

    Request: https://api.us-east-1.communicate.engageone.co/video/12421fdfsncjdsnj/data/21s21s21s-43ea-4ad9-894b-s212s2
Headers:
      {
        PB-Customer-Id: "sa11bb"
        Authorization: "Bearer eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f"
      }
Body: {
    "videoUrl": "https://watch.engageone.co/644a14ee676f3cff105c66be/{{pbpxsystem.data_record_uuid}}", 
    "feedbackId": "EBz1BdFbIAMCKPA="
}
Example Response:
    {
    "uuid": "dsfdsf33-c2a5-4700-9cba-fdsfdsf"
    }

  8. Get url for generated file (https://docs.api.communicate.engageone.co/#/data/getVideoDatasourceDownloadURL).

    Request: https://api.us-east-1.communicate.engageone.co/video/data/dsfdsf33-c2a5-4700-9cba-fdsfdsf
Headers:
    {
        PB-Customer-Id: "sa11bb"
        Authorization: "Bearer eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f"
    }
Example Responses:{} - when response is empty it means that file is still 
generated
    {
        "url":https://eocm-company--sa11bb--production--us-
east-1.s3.amazonaws.com/data/video/fa8e4442-a410-43a7-b538-
12e76433a259.csv?AWSAccessKeyId=dasdsadsad&Signature=JI%asdasd%
2FniITvBd%2F0Uc%3D&x-amz-security-
token=IQoJb3JpZ2luX2VjED4aCXVzLWVhc3QtMSJGMEQCIBI5uB3NWjD3vnVFkFDO6kQGYNGNo%
2FwessBZYWQDH5j8AiBTH%2FusmBhRam0h2bp2rtD6uxKoZ8xDzz4QJl%
sadsadas%2BgSPY1y9YfmHei4TToLXeysfVavM15O%
2BjZr3nksgpy0KNtx8I9dXwv9O2dz6vKvBQepIxBDBgwBoZJDl8IugiaAYAOqfdsO&Expires=1682605202
}

Transfer communications

  1. Create the Example_transfer email communication in the Samples project.
  2. Create the client credentials in source account (this can be done in Account Settings).

    Example data:

    CustomerId: sa11bb,
ClientId: sa11bb.11122223333444@comunnicate.engageone.co
Secret: aabbcc

  3. Create client credentials in target account (this can be done in Account Settings).

    Example data:

    CustomerId: sa22cc, 
ClientId: sa22cc.21e2e121e21e21e@comunnicate.engageone.co
Secret: ccccbbbbaaaa

  4. Get authorization token for source account (https://docs.api.communicate.engageone.co/users.html#/auth/authenticate).

    Request: https://usersapi.communicate.engageone.co/authenticate
Body:
    {
        "client_id": "sa11bb.11122223333444@comunnicate.engageone.co",
        "secret": "aabbcc",
        "customer_id": "sa11bb"
    }
Example response:  
    "eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f"

  5. Get authorization token for target account (https://docs.api.communicate.engageone.co/users.html#/auth/authenticate).

    Request: https://usersapi.communicate.engageone.co/authenticate 
Body:  
    { 
        "client_id": "sa22cc.21e2e121e21e21e@comunnicate.engageone.co", 
        "secret": "ccccbbbbaaaa", 
        "customer_id": "sa22cc" 
    } 
Example response:  
    "eyd327hd3278hd.d32gyd8yg32d8yg3287d32hd732gd78g3.duh32dh832d8h32hd8h8732"

  6. Transfer communication (https://docs.api.communicate.engageone.co/api.html#/transfer/initCommunicationTransfer).

    Request: https://api2.production.us-east-1.communicate.engageone.co/project/Samples/communication/Example_transfer/transfer
Headers:
    {
        "PB-Customer-Id": "sa11bb",
        "authorization": "Bearer eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f",
        "targetAuthToken": "Bearer eyd327hd3278hd.d32gyd8yg32d8yg3287d32hd732gd78g3.duh32dh832d8h32hd8h8732"
    }
Body: 
    {
        "sourceRegionName": "us-east-1",
        "sourceSubscriptionId": "sa11bb",
        "targetRegionName": "eu-central-1",
        "targetSubscriptionId": "sa22cc",
        "targetCommunicationName": "newTargetCommunication",
        "targetProjectName": "newTargetProject",
        "environment": "production",
        "deleteOrigin": true,
        "copyDataSource": true
    }
Example Response: 
    {
        "data": 
            {
                "id": "dasd2-d2d-2ddsad-9685-xxxx"
            },
        "status": "success"
    }

  7. Check status of transfer (https://docs.api.communicate.engageone.co/api.html#/transfer/getCommunicationTransferStatus).

    Request: https://api2.production.us-east-1.communicate.engageone.co/project/Samples/communication/Example_transfer/transfer/dasd2-d2d-2ddsad-9685-xxxx
Headers:
    {
        "PB-Customer-Id": "sa11bb",
        "authorization": "Bearer eyd23u9dh239udh923hf.4fh873f8hujf9aj87hfuhfuidhuifh93hu.f34298fh3ufh934hfj9348f34h9f"
    }
Example Response:
    {
        "data": 
            {
                "uuid": "sadsa-da3d3ad-dsa4f3f-13f2f23-g54g45",
                "start_time": 1682673740,
                "end_time": 1682673758,
                "status": "finished",
                "type": "email_transfer",
                "params":
                    {
                        "source": {
                            "region": "us-east-1",
                            "subscriptionId": "sa11bb",
                            "communication": 
"Example_transfer",
                            "project": "Samples"
                                  },
                        "target": 
                                  {
                             "region": "eu-west-2",
                             "subscriptionId": "sa22cc",
                              "communication": 
"newTargetCommunication",
                            "project": "newTargetProject"
                                  },
                        "details": 
                                  {
                            "environment": "production",
                            "deleteOrigin": false,
                            "jobId": "dasd2-d2d-2ddsad-9685-
xxxx",
                            "startTime": "1682673740",
                            "copyDataSource": false,
                            "copyAttachments": true
                                  }
                    },
            "success": true
        }
    }