RDstation ruby wrapper to interact with RDStation API.
Upgrading? Check the migration guide before bumping to a new major version.
Add this line to your application's Gemfile:
gem 'rdstation-ruby-client'
And then execute:
$ bundle
Or install it yourself as:
$ gem install rdstation-ruby-client
Before getting youre credentials, you need to configure client_id and client_secret as following:
RDStation.configure do |config|
config.client_id = YOUR_CLIENT_ID
config.client_secret = YOUR_CLIENT_SECRET
end
For details on what client_id
and client_secret
are, check the developers portal.
For more details, check the developers portal.
rdstation_authentication = RDStation::Authentication.new
redirect_url = 'https://yourapp.org/auth/callback'
rdstation_authentication.auth_url(redirect_url)
You will need the code param that is returned from RD Station to your application after the user confirms the access at the authorization dialog.
rdstation_authentication = RDStation::Authentication.new
rdstation_authentication.authenticate(code_returned_from_rdstation)
# => { 'access_token' => '54321', 'expires_in' => 86_400, 'refresh_token' => 'refresh' }
rdstation_authentication = RDStation::Authentication.new
rdstation_authentication.update_access_token('refresh_token')
NOTE: This is done automatically when a request fails due to access_token expiration. To keep track of the new token, you have to provide a callback block in configuration. For example:
RDStation.configure do |config|
config.client_id = YOUR_CLIENT_ID
config.client_secret = YOUR_CLIENT_SECRET
config.on_access_token_refresh do |authorization|
# authorization.access_token_expires_in is the time (in seconds for with the token is valid)
# authorization.access_token is the new token
# authorization.refresh_token is the existing refresh_token
#
# If you are using ActiveRecord, you may want to update the stored access_token, like in the following code:
MyStoredAuth.where(refresh_token: authorization.refresh_token).update_all(access_token: authorization.access_token)
end
end
RDStation::Authentication.revoke(access_token: "your token")
Note: this will completely remove your credentials from RD Station (update_access_token
won't work anymore).
Returns data about a specific Contact
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.contacts.by_uuid('uuid')
More info: https://developers.rdstation.com/reference/get_platform-contacts-identifier-value
Returns data about a specific Contact
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.contacts.by_email('email')
More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodGetDetailsuuid
Updates the properties of a Contact.
contact_info = {
name: "Joe Foo"
}
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.contacts.update('uuid', contact_info)
Contact Default Parameters
- name
- job_title
- personal_phone
- mobile_phone
- website
- tags
More info: https://developers.rdstation.com/reference/patch_platform-contacts-identifier-value
With an UPSERT like behavior, this method is capable of both updating the properties of a Contact or creating a new Contact. Whatever is used as an identifier cannot appear in the request payload as a field. This will result in a BAD_REQUEST error.
contact_info = {
name: "Joe Foo"
}
identifier = "email"
identifier_value = "joe@foo.bar"
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.contacts.upsert(identifier, identifier_value, contact_info)
More info: https://developers.rdstation.com/reference/patch_platform-contacts-identifier-value
The events endpoint are responsible for receiving different event types in which RD Station Contacts take part in.
It is possible to send default events to RD Station such as conversion events, lifecycle events and won and lost events. Also, RD Station supports the possibility of receiving different event types, for instance, chat events, ecommerce ones and others.
Check the developers portal to learn about the required payload structure and which events are available.
This creates a new event on RDSM:
payload = {} # hash representing the payload
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.events.create(payload)
Endpoints to manage Contact Fields information in your RD Station account.
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.fields.all
payload = {} # hash representing the payload
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.fields.create payload
Or you can use the new RDStation::Builder::Field
payload = {} # hash representing the payload
builder = RDStation::Builder::Field.new payload['api_identifier']
builder.data_type(payload['data_type'])
builder.presentation_type(payload['presentation_type'])
builder.name('pt-BR', payload['name'])
builder.label('pt-BR', payload['label'])
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.fields.create builder.build
payload = {} # hash representing the payload
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.fields.update('FIELD_UUID', payload)
Or you can use the new RDStation::Builder::Field
payload = {} # hash representing the payload
builder = RDStation::Builder::Field.new payload['api_identifier']
builder.data_type(payload['data_type'])
builder.presentation_type(payload['presentation_type'])
builder.name('pt-BR', payload['name'])
builder.label('pt-BR', payload['label'])
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.fields.update('FIELD_UUID', builder.build)
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.fields.delete('FIELD_UUID')
Webhooks provide the ability to receive real-time data updates about your contact activity.
Choose to receive data based on certain actions, re-cast or marked as an opportunity, and have all applicable data sent to a URL of your choice. You can then use your own custom application to read, save, and do actions with that data. This is a powerful option that allows you to keep all your data in sync and opens the possibility for all types of integration.
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.webhooks.all
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.webhooks.by_uuid('WEBHOOK_UUID')
payload = {} # payload representing a webhook
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.webhooks.create(payload)
The required strucutre of the payload is described here.
payload = {} # payload representing a webhook
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.webhooks.create('WEBHOOK_UUID', payload)
The required strucutre of the payload is described here
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.webhooks.delete('WEBHOOK_UUID')
Endpoints to Email information in your RD Station account.
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.emails.all
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
query_params = {page_size: 10, page: 1}
client.emails.all(query_params)
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.emails.by_id(id)
Endpoints to Segmentation information in your RD Station account.
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.segmentations.all
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.segmentations.contacts(segmentation_id)
Endpoints to Analytics information in your RD Station account.
Endpoints to Analytics - Email marketing information in your RD Station account.
- NOTE: The query params
start_date
(yyyy-mm-dd) andend_date
(yyyy-mm-dd) are required
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
query_params = { start_date:'2022-11-02', end_date:'2022-11-08' }
client.analytics.email_marketing(query_params)
Endpoints to Analytics - Conversions information in your RD Station account.
- NOTE: The query params
start_date
(yyyy-mm-dd) andend_date
(yyyy-mm-dd) are required.
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
query_params = { start_date:'2022-11-13', end_date:'2022-11-15', assets_type:['LandingPage'] }
client.analytics.conversions(query_params)
Endpoints to LandingPages information in your RD Station account.
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.landing_pages.all
Returns the account information.
client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.account.info
=> {"name"=>"www.rdstation.com"}
Each endpoint may raise errors accoording to the HTTP response code from RDStation:
RDStation::Error::BadRequest
(400)RDStation::Error::Unauthorized
(401)RDStation::Error::Forbidden
(403)RDStation::Error::NotFound
(404)RDStation::Error::MethodNotAllowed
(405)RDStation::Error::NotAcceptable
(406)RDStation::Error::Conflict
(409)RDStation::Error::UnsupportedMediaType
(415)RDStation::Error::UnprocessableEntity
(422)RDStation::Error::TooManyRequests
(429)RDStation::Error::InternalServerError
(500)RDStation::Error::NotImplemented
(501)RDStation::Error::BadGateway
(502)RDStation::Error::ServiceUnavailable
(503)RDStation::Error::ServerError
(which is returned for 5xx errors different than 500, 501, 502 or 503)
In case of a Bad Request (400), the following specific errors may be raised (those are subclasses of RDStation::Error::BadRequest
):
RDStation::Error::ConflictingField
RDStation::Error::InvalidEventType
In cause of Unauthorized (401), the following specific errors may be raised (those are subclasses of RDStation::Error::Unauthorized
):
RDStation::Error::ExpiredAccessToken
RDStation::Error::ExpiredCodeGrant
RDStation::Error::InvalidCredentials
Any error class has a details
method which returns the specific error message and the http_status.
See CHANGELOG.md
v2.0.0 main change is that it drops support for RDSM's old 1.x API. If you're not familiar with the 2.0 API yet, check it out first. Also take a look at the release notes, as they explain the changes in greater detail.
So, here is a step-by-step guide on how to upgrade your app:
- Ensure you're using
ruby >= 2.0.0
. - Remove every direct instantiation of
RDStation::Contacts
,RDStation::Events
,RDStation::Fields
andRDStation::Webhooks
and useRDStation::Client
to get them instead. - Replace any call of
RDStation::Client#create_lead
,RDStation::Client#change_lead
orRDStation::Client#change_lead_status
with the equivalent method in the Contacts API. - Review your error handling, as more options are available now.
http_status
method will always return nil. To get the status now useerror.details[:http_status]
or check the type of the class.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
You can check out RDstation's integration documentation at our developers portal.