Creates or updates a subscriber and sends a welcome message if the subscriber is new to the channel. New subscribers are subscribed to the channel. If the subscriber already exists and is unsubscribed
, a 405 Method Not Allowed will returned. You must honor the users request to not recieve further messages. See Compliance documentation.
This function transactionally updates the subscriber, their tags and properties, and then sends a welcome. This means that any failure implies that the changes were not persisted and no message was sent.
This end point allows the updating of email_address
,external_user_id
, tags, and properties. Tags and properties specified for existing subscribers are merged. To replace the values, use the reset
flag.
The welcome message can be specified in the request or a welcome series configured on the channel can be sent. It is an error to specify both a welcome message and request that a series be sent. It is also an error to request a welcome series when no series has been configured on the channel. Welcome series tagging is applied when determining which welcome series to send, which matches the subscriber's tags to some welcome series. If there is no matching series, the default series is sent.
In addition to sending welcome series, the more recent workflow feature is also available through this API. By specifying the workflow to start and any necessary arguments, it is possible to start a workflow after updating the subscriber. Note that if the conditions for starting the workflow are not met, the workflow is not executed for the subscriber.
A note on HTTP status codes that upsert can return
Note: If are planning to make > 1000 calls to this end point in a single session, it would be better to use our enterprise bulk upsert end point. Please request access via support@chatitive.com.
Response format | JSON |
---|---|
Requires authentication? | Yes |
phone_number required | The customer's phone number. |
---|---|
email_address optional | The customer's email address. |
external_user_id optional | External ID for the customer. |
properties optional | Properties to set for the subscriber. An empty hash will clear the subscriber's properties. |
tag_sids optional | An array of Tag SIDs to add to the subscriber. An empty array will clear the subscriber's tags. |
reset optional | A boolean indicating that the subscriber's properties and tags should be cleared before applying the specified tags and properties. |
welcome_message_body optional | The welcome message text to send to the subscriber if they are new. This param is mutually exclusive with |
send_welcome_series optional | A boolean indicating that a welcome series configured on the channel should be sent if the subscriber is new. This param is mutually exclusive with |
workflow_sid_to_start optional | The |
workflow_kwargs optional | A dictionary of arguments to pass to the workflow being started. |
status optional | The subscriber |
curl \
-X POST \
-u '[SID]:[TOKEN]' \
-H 'Content-Type: application/json' \
-d '{
"email_address": "joe@example.com",
"external_user_id": "12357111317",
"properties": {
"firstName": "Joe",
"lastName": "Smith"
},
"tag_sids": ["p03Gjl8Uzn0RkZSpHXHnrw"],
"send_welcome_series": true
}' \
'https://api.essential.to/v2/account/channels/p03Gjl8Uzn0RkZSpHXHnrw/subscribers/15009998080/upsert_and_welcome'
# Sample response
{
"phone_number": "5009998080",
"status": "subscribed",
"subscribed_at": "2017-01-25T21:43:04.618Z",
"unsubscribed_at": null,
"created_at": "2017-01-25T21:43:04.620Z",
"updated_at": "2017-01-25T21:43:04.620Z",
"carrier": "AT&T Wireless",
"carrier_updated_at": "2017-01-25T21:43:04.618Z",
"added_to_inbox_at": null,
"sid": "daBoeXvpfadRPgyYaaZJpw",
"account_sid": "p03Gjl8Uzn0RkZSpHXHnrw",
"channel_sid": "p03Gjl8Uzn0RkZSpHXHnrw",
"transport_sid": "p03Gjl8Uzn0RkZSpHXHnrw"
}
Python coming soon.
Node coming soon.