Text Variation

1. Overview

The TextVariation API generates variations of a source text while preserving its general context. Depending on the configuration enabled for the customer, processing may use AI generation, synonyms, and other Witime-managed strategies.

This document describes the public endpoint, its parameters, and integration examples. All values shown below are fictitious.

2. Endpoint

POST <BASE_URL>/witime/chatbot/textvariation.aspx?chave=<ACCESS_KEY>

Production URL example:

https://sms.witi.me/witime/chatbot/textvariation.aspx?chave=<ACCESS_KEY>

Witime provides the final URL, access key, company identifier, and configuration name.

Headers

Header	Value
Content-Type	application/json; charset=utf-8
Accept	application/json

Authentication

Authentication uses the chave query parameter.

• Use HTTPS outside local development environments.
• Never hard-code the access key in source code.
• Store it in an environment variable or secret vault.
• Do not share full URLs containing the key in tickets, screenshots, or logs.
• The Chave returned under Resultado is a request identifier, not an authentication credential.

3. Request body

{
  "Configuracao": "gpt-sinonimos-rcs",
  "Texto": "Offer available! Read the terms and learn more: https://example.com/offer",
  "NumeroVariacoes": 3,
  "MaxTextLength": 155,
  "RemoveAcentos": false,
  "RemoveUnicode": false,
  "IdEmpresa": 12345
}

12345, example.com, and the message content are demonstration data only.

Fields

Field	Type	Required	Description
Configuracao	string	Yes	Exact configuration name enabled by Witime, such as gpt-sinonimos-rcs.
Texto	string	Yes	Source text to vary. It must not be empty.
NumeroVariacoes	integer	Yes	Requested number of final variations. Use a positive integer within contractual limits.
MaxTextLength	integer	Recommended	Desired maximum length for each text. The service uses 160 when the value is lower than 1.
RemoveAcentos	boolean	No	Removes diacritics when true. Default: true.
RemoveUnicode	boolean	No	Removes unsupported Unicode characters and also forces diacritic removal when true. Default: true. Use false when emojis are allowed.
IdEmpresa	integer	Yes	Company identifier provided by Witime.

Processing notes

• Links are protected during variation and restored in the output.
• The complete original link should be present in the result; the client should still validate it before sending a message.
• The service may reuse previously processed variations from cache.
• Invalid, duplicate, or rule-incompatible candidates may be discarded.
• The client must review generated content before use, especially prices, dates, commercial terms, legal wording, and opt-out instructions.

4. cURL example

Keep sensitive values outside the command and replace the sample values:

export WITIME_BASE_URL="https://sms.witi.me"
export WITIME_API_KEY="your-key-provided-by-witime"

curl --request POST \
  "${WITIME_BASE_URL}/witime/chatbot/textvariation.aspx?chave=${WITIME_API_KEY}" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "Accept: application/json" \
  --data '{
	"Configuracao": "gpt-sinonimos-rcs",
	"Texto": "Offer available! Read the terms and learn more: https://example.com/offer",
	"NumeroVariacoes": 3,
	"MaxTextLength": 155,
	"RemoveAcentos": false,
	"RemoveUnicode": false,
	"IdEmpresa": 12345
  }'

5. PowerShell example

$baseUrl = $env:WITIME_BASE_URL
$apiKey = [Uri]::EscapeDataString($env:WITIME_API_KEY)
$uri = "$baseUrl/witime/chatbot/textvariation.aspx?chave=$apiKey"

$body = @{
	Configuracao = "gpt-sinonimos-rcs"
	Texto = "Offer available! Read the terms and learn more: https://example.com/offer"
	NumeroVariacoes = 3
	MaxTextLength = 155
	RemoveAcentos = $false
	RemoveUnicode = $false
	IdEmpresa = 12345
} | ConvertTo-Json

$response = Invoke-RestMethod `
	-Method Post `
	-Uri $uri `
	-ContentType "application/json; charset=utf-8" `
	-Headers @{ Accept = "application/json" } `
	-Body $body

if ($response.Resultado.CodigoResultado -ne 0) {
	throw "TextVariation failed: $($response.Resultado.Mensagem)"
}

$response.Variacoes | ForEach-Object { $_.Texto }

6. Successful response

{
  "Variacoes": [
	{
	  "Texto": "Offer available! Review the terms and learn more: https://example.com/offer",
	  "Toxidades": 0
	},
	{
	  "Texto": "Check the offer and read its terms: https://example.com/offer",
	  "Toxidades": 0
	},
	{
	  "Texto": "Learn more about the offer and its terms: https://example.com/offer",
	  "Toxidades": 0
	}
  ],
  "Resultado": {
	"CodigoResultado": 0,
	"Mensagem": "3 textos gerados com sucesso",
	"Chave": "00000000-0000-0000-0000-000000000000",
	"Cobrado": true,
	"ValorCobrado": 3.0,
	"ElapsedTimeMS": 2500
  }
}

The response above is illustrative. Texts, quantities, identifiers, and processing time vary on every request.

Response fields

Field	Type	Description
Variacoes	array	Returned variation list.
Variacoes[].Texto	string	Final variation text.
Variacoes[].Score	string or null	Content classification when available. It may be omitted.
Variacoes[].Toxidades	integer	Toxicity indicator associated with the variation. Toxidades is the exact contract field name.
Resultado.CodigoResultado	integer	0 means success. Other values indicate a business or processing error.
Resultado.Mensagem	string	Human-readable result description. Messages may be returned in Portuguese.
Resultado.Chave	UUID	Response correlation identifier. It is not the access key.
Resultado.Cobrado	boolean	Indicates whether consumption was recorded.
Resultado.ValorCobrado	decimal	Consumption value recorded by the service. Confirm its unit in the commercial agreement; it may differ from the size of Variacoes.
Resultado.ElapsedTimeMS	integer	Server-side elapsed time in milliseconds.

Always inspect Resultado.CodigoResultado to determine success. Do not rely exclusively on the HTTP status or Mensagem text.

7. Known result codes

Code	Meaning
0	Processing completed successfully.
1	Missing access key or missing/invalid configuration, according to the message.
2	Empty request body.
3	Invalid JSON.
4	Empty text after validation.
5	Insufficient balance to generate variations.

Access-key validation and internal components may return additional codes. For support, record CodigoResultado, Mensagem, and Chave, but never log the access key or sensitive content.

Error example

{
  "Variacoes": [],
  "Resultado": {
	"CodigoResultado": 5,
	"Mensagem": "Saldo insuficiente para gerar variações de texto.",
	"Chave": "00000000-0000-0000-0000-000000000000",
	"Cobrado": false,
	"ValorCobrado": 0.0,
	"ElapsedTimeMS": 20
  }
}

8. Integration recommendations

1. Configure an HTTP timeout suitable for AI processing; requests may take several seconds.
2. Treat the actual returned list size as the effective result count.
3. Do not retry indiscriminately: a request may record consumption even if its response is lost. No idempotency guarantee is documented.
4. For transient failures, use a small number of retries with exponential backoff and retain the correlation Chave when available.
5. Validate length, links, opt-out wording, mandatory information, and business rules for every variation.
6. Do not send personal or confidential data without a lawful basis, contractual authorization, and appropriate controls.
7. Preserve the exact JSON field spelling, including Configuracao, NumeroVariacoes, IdEmpresa, and Toxidades.

9. Acceptance checklist

• Production URL received through a secure channel.
• Access key stored in a secret vault or environment variable.
• IdEmpresa and Configuracao confirmed by Witime.
• Timeout and error handling configured.
• CodigoResultado checked on every response.
• Output links compared with the source text.
• Character limits validated by the client.
• Content and opt-out wording reviewed before sending.
• Logs contain no credentials, personal data, or complete message bodies.

10. Support information

When requesting support, provide only:

• request date and time, including time zone;
• environment name;
• Resultado.CodigoResultado;
• Resultado.Mensagem;
• Resultado.Chave;
• IdEmpresa, when authorized;
• technical parameters without the full source text whenever possible.

Never send the complete access key. Mask personal data, private links, and confidential content as well.