Social events

Acoustic Exchange has identified and defined recognized events that typically happen as customers
interact with businesses over social media.

As an endpoint publisher, call https://api-exchange-us-1.goacoustic.com/v1/event to publish the event. The following example illustrates a typical JSON payload.

This example is based on the Facebook Post event.

POST v1/event
{  
  “channel” : “Social”,
  “identifiers” : [            
    {
    “name” : “email”,
    “value” : “[email protected]”
    }
    ],
  “events” : [
    { 
    “code” : “x1fbPost”, 
    “timestamp” : “2015-11-03T21:14:12Z”, 
    “attributes” : [
      {
      “name” : “eventName”,            
      “value” : “Facebook Post”,  
      “type” : “string” 
      } 
      {
      “name” : “body”,            
      “value” : “”,  
      “type” : “string” 
      }      
      {
      “name” : “sentimentScore”,            
      “value” : “3”,  
      “type” : “integer” 
      }   
      {
      “name” : “sentiment”,            
      “value” : “negative”,  
      “type” : “string” 
      }  
      ]
    }   
  ]
}

Facebook post

Information that describes a post to Facebook.

Event code: x1fbPost
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Facebook Post

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

tags

string

<value<

Add one or more tags that you define as necessary.

body

string

Text body of the post.

sentimentScore

number

Numerical ranking for the sentiment of the post.

Yes

sentiment

string

Overall sentiment of the post. Example: positive, negative, or neutral.

pageName

string

The name of the Facebook page being tracked.

Facebook comment

Information that describes a comment on Facebook.

Event code: x1fbComment
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Facebook Comment

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

tags

string

Add one more tags that you define as necessary.

body

string

Text body of the post.

Yes

sentimentScore

number

Overall sentiment of the post. Example, positive, negative, or neutral.

sentiment

string

The name of the Facebook page being tracked.

pageName

string

The name of the Facebook page being tracked.

Facebook like post

Information that describes a Facebook like posting.

Event code: x1fbPost
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Facebook Like Post

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

tags

string

Add one or more tags that you define as necessary.

body

string

Text body of the post.

Yes

Facebook like page

Information that describes a Facebook like page.

Event code: x1fbLikePage
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Facebook Like Post

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

tags

string

<value<

Add one or more tags that you define as necessary.

pageName

string

The name of the Facebook page being tracked.

Twitter shared

Information to describe what happens when an individual shares a tweet that is related to a tracked product or brand.

Event code: x1twitterShared
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Twitter shared

Name of the event as it appears in the Acoustic Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

tags

string

The name of the brand being tracked.

sentimentScore

number

Numerical ranking for the sentiment of the tweet.

sentiment

string

Overall sentiment of the shared tweet. Example: positive, negative, or neutral.

Twitter tweeted

Information to describe a tweet that is related to a tracked brand or
product.

Event code: x1twitterTweeted
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Twitter Tweeted

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

tags

string

Add one or more tags that you define as necessary.

sentimentScore

number

Numerical ranking for the sentiment of the tweet.

sentiment

string

Overall sentiment of the tweet. Example: positive, negative, or neutral.

body

string

Text body of the tweet.

Twitter retweeted

Information to describe a re-tweet.

Event code: x1twitterRetweeted
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Twitter Retweeted

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

Add one or more tags that you define as necessary.

tags

string

Add one or more tags that you define as necessary.

sentimentScore

string

Numerical ranking for the sentiment of the retweet.

sentiment

number

Numerical ranking for the sentiment of the retweet.

body

string

Text body of the retweet.

Twitter mentioned

Information to describe mention of a brand or product in a tweet or retweet.

Event code: x1twitterMentioned
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Twitter Mentioned

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

mentionedName

string

The handle of the Twitter user (@username) being mentioned.

tags

string

Add one or more tags that you define as necessary.

sentimentScore

number

Numerical ranking for the sentiment of the tweet.

sentiment

string

<value

Overall sentiment of the tweet. Example: positive, negative, or neutral.

body

string

Text body of the tweet.

Twitter replied

Information that describes a Twitter reply that is related to a product or
brand.

Event code: x1twitterReplied
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Twitter Replied

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

tags

string

Add one more more tags that you define as necessary.

sentimementScore

number

Numerical ranking for the sentiment of the reply.

sentiment

string

Overall sentiment of the reply. Example: positive, negative, or neutral.

body

string

Text body of the reply.

Twitter followed

Information that relates to a twitter user who starts to follow the Twitter feed for a product or brand.

Event code: x1twitterFollowed
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Identify the type (name) of the conversion that occurred. Example: form download.

eventName

string

Twitter Followed

Name of the event as it appears in the Exchange user interface.

brandTag

string

The name of the brand being tracked.

tags

string

Add one or more tags that you define necessary.

Twitter favorited

Event Code: x1twitterFavorited
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Identify the type event that occurred. Example: favorite.

eventName

string

Twitter Followed

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

tags

string

Add one or more tags that you define as necessary.

Instagram like post

Information to describe a like posting on Instagram that relates to a product or brand.

Event code: x1instagramLikePost
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Instagram Like Post

Name of the event as it appears in the Exchange user interface.

Yes

postType

string

The type of Instagram post (photo or video)

brandTag

string

The name of the brand being tracked.

tags

string

Add one or more tags that you define as neccessary.

sentimentScore

number

Numerical ranking of for the sentiment of the post.

sentiment

string

Overall sentiment of the post. Example: positive, negative, or neutral.

body

string

Text body of the post.

Instagram comment

Information to describe a comment on Instagram that relates to a brand or
product.

Event code: x1instagramComment
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable look up in the system.

eventName

string

Instagram Comment

Name of the event as it appears in the Exchange user interface.

Yes

postType

string

The type of Instagram post. (photo or video)

brandTag

string

The name of the brand being tracked.

tags

string

Add one or more tags that you define as necessary.

sentimentScore

number

Numerical ranking of the sentiment of the comment.

sentiment

string

Overall sentiment of the comment. Example: positive, negative, or neutral.

body

string

Text body of the comment.

Instagram followed

Information to describe the event of an Instagram account that relates to a brand or product being followed by a customer.

Event code: x1instagramFollowed
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Instagram Followed

Name of the event as it appears in the Exchange user interface.

Yes

userTag

string

The Instagram user account being followed by another Instagram user.

brandTag

string

The name of the brand being tracked.

tag

string

Add one or more tags that you define as necessary.

deviceType

string

MOBILEPHONE

The device used to follow the Instagram account.

campaignName

string

Spring Campaign

The name of the marketing campaign related to the Instagram followed event

latitude

string

42.5492895

The latitude of the user when the followed the Instagram account.

longitude

string

-71.4716739

The longitude of the user when they followed te Instagram account.

Instagram hastag

Information that describes a customer using a special Instagram hashtag that relates to a
product or brand.

Event code: x1instagramHashtag
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event to allow the user to better understand the context of the event.

eventId

string

12345

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Instagram Hashtag

Name of the event as it appears in the Exchange user interface.

Yes

hashTag

string

The special hashtag related to the product or brand.

brandTag

string

The name of the brand being tracked.

tag

string

Add one or more tags that you define as necessary.

body

string

The full text of the post.

campaignName

string

Spring Campaign

The name of the marketing campaign related the Instagram hashtag event.

Viewed coupon

Information that relates to an individual viewing a coupon offered by a product or brand.

Event code: couponViewed
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand then event context.

eventId

string

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Viewed Coupon

Name of the event as it appears in the Exchange user interface.

Yes

mailingId

number

12345

ID of the mailing that was used to send the offer.

mailingName

string

pageId

string

pageName

string

Name of the offer or coupon.

Claimed coupon

Information that relates to an individual claiming a coupon offered by a product or brand.

Event code: couponClaimed
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

Unique ID to identify the type of event and enable the lookup in the system.

eventName

string

Claimed Coupon

Name of the event as it appears in the Exchange user interface.

Yes

mailingId

number

12345

ID of the mailing that was used to send the offer.

mailingName

string

Name of the mailing that was used to send the offer.

campaignId

string

Identifies the specific marketing effort. Usually unique but might have multiple view IDs within a campaign.

campaignName

string

Name of the campaign. Often the name of the coupon.

claimId

number

Unique ID of the specific coupon being claimed.

itemName

string

Name of the specific item claimed within the coupon.

ItemDesc

string

Description of the item that is being claimed.

imageURL

string

Online location of the public image of the item that is being claimed.

Redeemed coupon

Information that relates to an individual redeeming a coupon offered by a product or brand.

Event code: couponRedeemed
Event attributes

Attributed Name

Data Type

Example

Description

Required

description

string

Description of the published event. Allow Exchange users to understand the event context.

eventId

string

6789

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Redeemed Coupon

Name of the event as it appears in the Exchange user interface.

mailingId

number

12345

ID of the mailing that was used to send the offer.

mailngName

string

Name of the mailing that used to send the offer.

CampaignId

string

Name of the mailing that was used to send the offer.

campaingName

string

Spring Campaign

Name of the campaign. Often the name of the coupon.

itemName

string

Office Chair

Name of the specific item claimed within the coupon.

redemptionId

string

The description of the item that was claimed.

Connected with social

Information that describes a customer connecting with a social networking site related to a product or brand.

Event code: connectedSocial
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event to allow the user to better understand the context of the event.

eventId

string

12345

Unique ID to identify the type of event and enable lookup in the system.

Yes

eventName

string

Connected with Social

Name of the event as it appears in the Exchange user interface.

brandTag

string

The name of the brand being tracked.

userType

string

First Time User

The type of customer connect event.

socialPlatform

string

Twitter

The social network platform the customer is using.

deviceType

string

MOBILEPHONE

The device used to make the connection.

campaignName

string

Spring Campaign

The name of the marketing campaign related to the Twitter hashtag event.

Disconnected from social

Information that describes a customer disconnecting with a social networking site related to a product or brand.

Event code: disconnectedSocial
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event to allow the user to better understand the context of the event.

eventId

string

12345

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Connected with Social

Name of the event as it appears in the Exchange user interface.

Yes

brandTag

string

The name of the brand being tracked.

userType

string

First Time User

The type of customer connect event.

socialPlatform

string

Twitter

The social network platform the customer is using.

deviceType

string

MOBILEPHONE

The device used to make the connection.

campaignName

string

Spring Campaign

The name of the marketing campaign related the Twitter hashtag event.

Question answered

Information that describes a customer answering a question in a survey or quiz format.

Event code: x1questionAnswered
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event to allow the user to better understand the context of the event.

eventId

string

12345

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Question Answered

Name of the event as it appears in the Acoustic Exchange user interface.

Yes

questionText

string

The text of a question in the survey.

answerText

string

Answer 1, Answer 2

One or more survey answers separated by commas.

correctness

string

1

The correctness of the questions answered with “0” meaning incorrect and “1” meaning correct.

propertyName

string

Gender

A property name that is independent of the wording of a question.

bundleName

string

If this question is part of a multi-question survey or quiz, this is the name for the
question bundle.

brandTag

string

The name of the brand being tracked.

tags

string

Add one or more tags that you define as necessary.

campaignName

string

Spring Campaign

The name of the marketing campaign related to the survey or quiz.

Referred or shared link

Information that describes one customer referring or sharing a link, related to a product or brand, that other individuals have followed.

Event code: x1link Referrel
Event attributes

Attribute Name

Data Type

Example

Description

Required

description

string

Description of the published event to allow the user to better understand the context of the event.

eventId

string

12345

Unique ID to identify the type of event and enable lookup in the system.

eventName

string

Question Answered

Name of the event as it appears in the Exchange user interface.

Yes

linkURL

string

The URL that is referred or linked to.

referralNumber

string

12

The number of unique individuals who have followed the link.

conversation Number

string

10

The number of downstream conversations.

brandTag

string

The name of the brand being tracked?

tags

string

Add one or more tags that you define as necessary.

campaignName

string

Spring Campaign

The name of the marketing campaign related to the referred or shared link.