# Using TransactionAttributes


You use the `TransactionAttributes` data structure to store application-specific information, such as call states or meeting IDs, and then pass that data to AWS Lambda invocations. This structure removes the need for storing data in external databases such as Amazon DynamoDB. 

`TransactionAttributes` are [JSON Objects](https://www.w3schools.com/js/js_json_objects.asp) that contain key/value pairs. The objects can contain a maximum of 100 key/value pairs, and the objects have a maximum payload size of 20 KB. The data in a `TransactionAttributes` structure persists for the life of a transaction.

When an AWS Lambda function passes `TransactionAttributes` to a SIP media application, the application updates any stored attributes. If you pass a `TransactionAttributes` object with an existing key set, you update the stored values. If you pass a different key set, you replace the existing values with the values from that different key set. Passing an empty map ( `{}` ) erases any stored values.

**Topics**
+ [

# Setting TransactionAttributes
](set-trans-attributes.md)
+ [

# Updating TransactionAttributes
](update-trans-attributes.md)
+ [

# Clearing TransactionAttributes
](clear-trans-attributes.md)
+ [

# Handling ACTION\$1SUCCESSFUL events
](attribute-trans-success.md)
+ [

# Invalid inputs
](attribute-trans-invalid.md)

# Setting TransactionAttributes


The following example shows how to set `TransactionAttributes` alongside a [PlayAudio](play-audio.md) action and pass the attributes from an AWS Lambda function to a SIP media application.

```
{
    "SchemaVersion": "1.0",
    "Actions": [
        {
            "Type": "PlayAudio",
            "Parameters": {
                "ParticipantTag": "LEG-A",
                "AudioSource": {
                    "Type": "S3",
                    "BucketName": "mtg1-sipmedia-app-iad",
                    "Key": "Welcome3.wav"
                }
            }
        }
    ],
    "TransactionAttributes": {
        "key1": "value1",
        "key2": "value2"
    }
}
```

# Updating TransactionAttributes


To modify stored `TransactionAttributes`, update the contents of the JSON object with new values. In the following example, the keys `NewKey1` and `NewKey2` are added to the `TransactionAttributes`. These keys are paired with the values `NewValue1` and `NewValue2`, respectively.

```
{
    "SchemaVersion": "1.0",
    "Actions": [
        {
            "Type": "PlayAudio",
            "Parameters": {
                "ParticipantTag": "LEG-A",
                "AudioSource": {
                    "Type": "S3",
                    "BucketName": "mtg1-sipmedia-app-iad",
                    "Key": "Welcome3.wav"
                }
            }
        }
    ],
    "TransactionAttributes": {
        "NewKey1": "NewValue1",
        "NewKey2": "NewValue2"
    }
}
```

If, in the previous example, you passed `NewValue1` to `key1`, the existing value of `key1` would be replaced with `NewValue1`. However, passing a value to `NewKey1` creates a new key/value pair.

# Clearing TransactionAttributes


To clear the contents of the `TransactionAttributes` object, pass the `TransactionAttributes` field with an empty JSON Object:

```
{
    "SchemaVersion": "1.0",
    "Actions": [
        {
            "Type": "PlayAudio",
            "Parameters": {
                "ParticipantTag": "LEG-A",
                "AudioSource": {
                    "Type": "S3",
                    "BucketName": "mtg1-sipmedia-app-iad",
                    "Key": "Welcome3.wav"
                }
            }
        }
    ],
    "TransactionAttributes": {
    }
}
```

**Note**  
You can't clear data from a `TransactionAttributes` structure by setting its value to `null`. Also, omitting the `TransactionAttribute` structure doesn't clear its data. Always pass an empty JSON object with `TransactionAttributes` to clear data from the object.

# Handling ACTION\$1SUCCESSFUL events


The following example shows how a successful [PlayAudio](play-audio.md) sends the stored `TransactionAttributes` as part of the `CallDetails `.

```
{ 
    "SchemaVersion": "1.0", 
    "Sequence": 2, 
    "InvocationEventType": "ACTION_SUCCESSFUL", 
    "ActionData": { 
        "Type": "PlayAudio", 
        "Parameters": { 
            "AudioSource": { 
                "Type": "S3", 
                "BucketName": "mtg1-sipmedia-app-iad", 
                "Key": "Welcome3.wav" 
            }, 
            "Repeat": 1, 
            "ParticipantTag": "LEG-A" 
        } 
    }, 
    "CallDetails": { 
        "TransactionId": "mtg1-tx-id", 
        "TransactionAttributes": { 
            "key1": "value1", 
            "key2": "value2" 
        }, 
        "AwsAccountId": "166971021612", 
        "AwsRegion": "us-east-1", 
        "SipRuleId": "aafbd402-b7a2-4992-92f8-496b4563c492", 
        "SipMediaApplicationId": "e88f4e49-dd21-4a3f-b538-bc84eae11505", 
        "Participants": [ 
            { 
                "CallId": "bbff30c5-866a-41b5-8d0a-5d23d5e19f3e", 
                "ParticipantTag": "LEG-A", 
                "To": "+14345550101", 
                "From": "+14255550199", 
                "Direction": "Inbound", 
                "StartTimeInMilliseconds": "1644539405907", 
                "Status": "Connected" 
            } 
        ] 
    } 
}
```

# Invalid inputs


The following example shows an invalid input. In this case, the JSON object passes too many items to a SIP media application.

```
{ 
    "SchemaVersion": "1.0", 
    "Actions": [ 
        { 
            "Type": "PlayAudio", 
            "Parameters": { 
                "ParticipantTag": "LEG-A", 
                "AudioSource": { 
                    "Type": "S3", 
                    "BucketName": "mtg1-sipmedia-app-iad", 
                    "Key": "Welcome3.wav" 
                } 
            } 
        } 
    ], 
    "TransactionAttributes": { 
        "key1": "value1", 
        "key2": "value2", 
        "key3": "value3", 
        "key4": "value4", 
        "key5": "value5", 
        "key6": "value6", 
        "key7": "value7", 
        "key8": "value8", 
        "key9": "value9", 
        "key10": "value10", 
        "key11": "value11" 
    } 
}
```

The following example shows the response to the previously given input. This output is passed from a SIP media application back to the AWS Lambda function that invoked the application.

```
{ 
    "SchemaVersion": "1.0", 
    "Sequence": 2, 
    "InvocationEventType": "INVALID_LAMBDA_RESPONSE", 
    "CallDetails": { 
        "TransactionId": "mtg1-tx-id", 
        "AwsAccountId": "166971021612", 
        "AwsRegion": "us-east-1", 
        "SipRuleId": "aafbd402-b7a2-4992-92f8-496b4563c492", 
        "SipMediaApplicationId": "e88f4e49-dd21-4a3f-b538-bc84eae11505", 
        "Participants": [ 
            { 
                "CallId": "72cbec69-f098-45d8-9ad6-e26cb9af663a", 
                "ParticipantTag": "LEG-A", 
                "To": "+14345550101", 
                "From": "+14255550199", 
                "Direction": "Inbound", 
                "StartTimeInMilliseconds": "1644540839987" 
            } 
        ] 
    }, 
    "ErrorType": "TransactionAttributesInvalidMapSize", 
    "ErrorMessage": "Transaction Attributes has too many mappings. Maximum number of mappings is 10" 
}
```